sugarjar 3.0.0 → 4.0.0

data/lib/sugarjar/help.rb

@@ -0,0 +1,313 @@
+class SugarJar
+  module Help
+    # Keyed by the "primary" command (the longest/most-descriptive name -
+    # not necessarily the actual method name in SugarJar::Commands, though
+    # both work identically for dispatch). `aliases` are other, usually
+    # shorter, names that dispatch to the same command. `description` is
+    # the full text shown by `sj help <command>`.
+    COMMANDS = {
+      'amend' => {
+        :aliases => [],
+        :usage => '',
+        :description => <<~DESC,
+          Amend the current commit. Alias for `git commit --amend`.
+          Accepts other arguments such as `-a` or files.
+        DESC
+      },
+      'amendq' => {
+        :aliases => ['qamend'],
+        :usage => '',
+        :description => <<~DESC,
+          Same as `amend` but without changing the message. Alias for
+          `git commit --amend --no-edit`.
+        DESC
+      },
+      'binfo' => {
+        :aliases => [],
+        :usage => '',
+        :description => 'Verbose information about the current branch.',
+      },
+      'br' => {
+        :aliases => [],
+        :usage => '',
+        :description => 'Verbose branch list. An alias for `git branch -v`.',
+      },
+      'debuginfo' => {
+        :aliases => [],
+        :usage => '',
+        :description => <<~DESC,
+          Prints out a bunch of version and config information useful for
+          including in bug reports.
+        DESC
+      },
+      'feature' => {
+        :aliases => ['f'],
+        :usage => '<branch_name>',
+        :description => <<~DESC,
+          Create a "feature" branch. It's morally equivalent to
+          `git checkout -b ...` except it defaults to creating it based on
+          some form of the primary branch (`master`, `main`, etc.) instead of
+          your current branch. In order of preference it will be
+          `upstream/$PRIMARY`, `origin/$PRIMARY`, `$PRIMARY`,
+          depending upon what remotes are available.
+
+          Note that you can specify `--feature-prefix` (or add `feature_prefix`
+          to your config's 'host_configs' section) to have all features created
+          with a prefix. This is useful for branch-based workflows where
+          developers are expected to create branches names that, for example,
+          start with their username.
+        DESC
+      },
+      'forcepush' => {
+        :aliases => ['fpush'],
+        :usage => '',
+        :description => <<~DESC,
+          The same as `smartpush`, but uses `--force-with-lease`. This is
+          a "safer" way of doing force-pushes and is the recommended way
+          to push after rebasing or amending. Never do this to shared
+          branches. Very convenient for keeping the branch behind a pull-
+          request clean.
+        DESC
+      },
+      'forcesync' => {
+        :aliases => ['fsync'],
+        :usage => '',
+        :description => <<~DESC,
+          Similar to `sync`, but never tries to rebase, always does a
+          hard reset.
+        DESC
+      },
+      'globalbranchclean' => {
+        :aliases => ['gbclean'],
+        :usage => '[<branch>] [<remote>]',
+        :description => <<~DESC,
+          WARNING: EXPERIMENTAL COMMAND.
+
+          Combination of `localbranchclean` and `remotebranchclean`. Cleans up
+          both local and remote branches safely. See those commands for
+          details.
+        DESC
+      },
+      'globalbranchcleanall' => {
+        :aliases => ['gbcleanall'],
+        :usage => '[<remote>]',
+        :description => <<~DESC,
+          WARNING: EXPERIMENTAL COMMAND.
+
+          Safely clean all branches, both local and remote. See
+          `globalbranchclean` for details.
+        DESC
+      },
+      'lint' => {
+        :aliases => [],
+        :usage => '',
+        :description => 'Run any linters configured in the repoconfig.',
+      },
+      'localbranchclean' => {
+        :aliases => %w{lbclean bclean},
+        :usage => '[<branch>]',
+        :description => <<~DESC,
+          If safe, delete the current branch (or the specified branch).
+          Unlike `git branch -d`, this can handle squash-merged branches.
+          Think of it as a smarter `git branch -d`.
+
+          Aliased to `bclean` for backwards compatibility.
+        DESC
+      },
+      'localbranchcleanall' => {
+        :aliases => %w{lbcleanall bcleanall},
+        :usage => '',
+        :description => <<~DESC,
+          Walk all branches, and try to delete them if it's safe. See
+          `localbranchclean` for details.
+
+          Aliased to `bcleanall` for backwards compatibility.
+        DESC
+      },
+      'modernizeconfig' => {
+        :aliases => ['fixconfig'],
+        :usage => '',
+        :description => <<~DESC,
+          Will take a sugarjar config file and modernize it for all of
+          the changes in 4.x. You will be given a diff, and you can choose
+          to overwrite the file, or save the new one to a new file.
+        DESC
+      },
+      'pullsuggestions' => {
+        :aliases => ['ps'],
+        :usage => '',
+        :description => <<~DESC,
+          Pull any suggestions *that have been committed* in the GitHub UI.
+          This will show the diff and prompt for confirmation before
+          merging. Note that a fast-forward merge will be used.
+        DESC
+      },
+      'remotebranchclean' => {
+        :aliases => ['rbclean'],
+        :usage => '[<branch>] [<remote>]',
+        :description => <<~DESC,
+          WARNING: EXPERIMENTAL COMMAND.
+
+          Similar to `localbranchclean`, except safely cleans up remote
+          branches. Unlike many git commands, <remote> comes after <branch> so
+          that you can specify a branch and the remote defaults to `origin`.
+          This means you can do `sj remotebranchclean` to clean the remote
+          branch with the same name as the local one. Note that you probably
+          want `globalbranchclean`, which will do both local and remote cleaning
+          in one command.
+
+          WARNING: This command cannot differentiate release branches
+          that are fully merged but still need to be kept around for future
+          work unless they are specified in your repoconfig! So if main contains
+          everything that 2.0-devel and 3.0-devel has, then those branches will
+          be deleted. Use with caution.
+        DESC
+      },
+      'remotebranchcleanall' => {
+        :aliases => ['rbcleanall'],
+        :usage => '[<remote>]',
+        :description => <<~DESC,
+          WARNING: EXPERIMENTAL COMMAND.
+
+          Walk all remote branches, and try to delete them if it's safe. See
+          `remotebranchclean` for details.
+        DESC
+      },
+      'smartclone' => {
+        :aliases => ['sclone'],
+        :usage => '<repo> [<dir>]',
+        :description => <<~DESC,
+          A smart wrapper to `git clone` that handles forking and managing
+          remotes for you.
+
+          If the org of the repository is not the same as your forge user
+          then it will fork the repo for you to your account (if not
+          already done), clone the repo, and then setup your remotes
+          so that `origin` is your fork and `upstream` is the upstream.
+
+          It is assumed that there will be at least one positional
+          argument, and it will be the repo in any format (git, ssh,
+          forge-style shortname [e.g. e.g. `$org/$repo`]). A second
+          positional argument will be interpreted as the directory to
+          clone into.
+
+          If you want to change the name of the repo in your fork of it,
+          you may pass in `--fork-name` to specify another.
+
+          Note that if you pass in additional options after " -- ", they
+          will be passed to `gh` in the case of GitHub, or `git` in the
+          case of GitLab.
+
+          For example to clone foo/bar/docs on gitlab, but have the
+          repo named "bar-docs" when it's cloned to your org, and to
+          have the directory be called "bar-docs":
+
+            sj sclone foo/bar/docs bar-docs \\
+              --default-forge-host gitlab.com --fork-name bar-docs
+
+          Or for GitHub:
+
+            sj sclone bar/docs bar-docs \\
+              --default-forge-host github.com --fork-name bar-docs
+        DESC
+      },
+      'smartlog' => {
+        :aliases => ['sl'],
+        :usage => '',
+        :description => <<~DESC,
+          Inspired by Facebook's `sl` extension to Mercurial, this command
+          will show you a tree of all your local branches relative to your
+          upstream.
+        DESC
+      },
+      'smartpullrequest' => {
+        :aliases => %w{smartpr spr},
+        :usage => '',
+        :description => <<~DESC,
+          A smart wrapper to `gh pr`/`glab mr`/etc. that checks if your repo
+          is dirty before creating the pull request, handles intelligently
+          picking the base, fills in the PR body, etc.
+        DESC
+      },
+      'smartpush' => {
+        :aliases => ['spush'],
+        :usage => '',
+        :description => <<~DESC,
+          A smart wrapper to `git push` that runs whatever is defined in
+          `on_push` in the repoconfig, and only pushes if they succeed.
+        DESC
+      },
+      'subfeature' => {
+        :aliases => ['sf'],
+        :usage => '<feature>',
+        :description =>
+          'An alias for `sj feature <feature> <current_branch>`.',
+      },
+      'sync' => {
+        :aliases => [],
+        :usage => '',
+        :description => <<~DESC,
+          Similar to `up`, except instead of rebasing on a tracked branch
+          (usually `upstream` remote), rebases to wherever our remote push
+          target is (usually `origin` remote). Useful for syncing work
+          across different machines.
+
+          For example, if you do some work on feature `foo` on machine1 and
+          push to `origin/foo` (intending to eventually merge to
+          `upstream/main`), then on machine2, you pull that branch, do more
+          work, which you also push to `origin/foo`, then on machine1, you
+          can do `sj sync` to pull down the changes from `origin/foo`. If
+          you have local changes, that are not already on `origin/foo`,
+          those will be rebased on top of the changes from `origin/foo`.
+        DESC
+      },
+      'unit' => {
+        :aliases => [],
+        :usage => '',
+        :description => 'Run any unitests configured in the repoconfig.',
+      },
+      'up' => {
+        :aliases => [],
+        :usage => '[<branch>]',
+        :description => <<~DESC,
+          Rebase the current branch (or specified branch) intelligently.
+          In most causes this will check for a primary branch on
+          `upstream`, then `origin`. If a branch explicitly tracks something
+          else, then that will be used, instead.
+        DESC
+      },
+      'upall' => {
+        :aliases => [],
+        :usage => '',
+        :description => 'Same as `up`, but for all branches.',
+      },
+    }.freeze
+
+    # Map of every valid command/alias name -> its canonical (primary) name.
+    ALIASES = COMMANDS.each_with_object({}) do |(name, info), map|
+      map[name] = name
+      info[:aliases].each { |a| map[a] = name }
+    end.freeze
+
+    def self.canonical(name)
+      ALIASES[name]
+    end
+
+    def self.summary_list
+      COMMANDS.sort.map do |name, info|
+        names = ([name] + info[:aliases]).join(', ')
+        "  #{names}"
+      end.join("\n")
+    end
+
+    def self.command_help(name)
+      canonical_name = canonical(name)
+      return nil unless canonical_name
+
+      info = COMMANDS[canonical_name]
+      names = ([canonical_name] + info[:aliases]).join(', ')
+      usage = info[:usage].empty? ? '' : " #{info[:usage]}"
+      "#{names}#{usage}\n\n#{info[:description]}"
+    end
+  end
+end

data/lib/sugarjar/repoconfig.rb

@@ -1,4 +1,4 @@
-require_relative 'util'
+require_relative 'git'
 require_relative 'log'
 require 'yaml'
 require 'deep_merge'
@@ -10,7 +10,7 @@ class SugarJar
     CONFIG_NAME = '.sugarjar.yaml'.freeze
 
     def self.repo_config_path(config)
-      ::File.join(SugarJar::Util.repo_root, config)
+      ::File.join(SugarJar::Git.repo_root, config)
     end
 
     def self.hash_from_file(config_file)
@@ -25,7 +25,7 @@ class SugarJar
 
     def self.config(config = CONFIG_NAME)
       data = {}
-      unless SugarJar::Util.in_repo?
+      unless SugarJar::Git.in_repo?
         SugarJar::Log.debug('Not in repo, skipping repoconfig load')
         return data
       end

data/lib/sugarjar/util.rb

@@ -30,70 +30,5 @@ class SugarJar
       end
       false
     end
-
-    def self.git_nofail(*args, color: true)
-      if %w{diff log grep branch}.include?(args[0]) &&
-         args.none? { |x| x.include?('color') }
-        args << (color ? '--color' : '--no-color')
-      end
-      SugarJar::Log.trace("Running: git #{args.join(' ')}")
-      Mixlib::ShellOut.new([which('git')] + args).run_command
-    end
-
-    def self.git(*, color: true)
-      s = git_nofail(*, :color => color)
-      s.error!
-      s
-    end
-
-    def self.ghcli_nofail(*)
-      forge_nofail('gh', *)
-    end
-
-    def self.ghcli(*)
-      s = ghcli_nofail(*)
-      s.error!
-      s
-    end
-
-    def self.glcli_nofail(*)
-      forge_nofail('glab', *)
-    end
-
-    def self.glcli(*)
-      s = glcli_nofail(*)
-      s.error!
-      s
-    end
-
-    def self.forge_nofail(cli, *args)
-      SugarJar::Log.trace("Running: #{cli} #{args.join(' ')}")
-      bin = which(cli)
-      s = Mixlib::ShellOut.new([bin] + args).run_command
-      if s.error? && s.stderr.include?("#{cli} auth")
-        SugarJar::Log.info(
-          'glab was run but no gitlab token exists. Will run ' +
-          '"glab auth login" to force\ngh to authenticate...',
-        )
-        unless system(bin, 'auth', 'login', '-p', 'ssh')
-          SugarJar::Log.fatal(
-            'That failed, I will bail out. Hub needs to get a github ' +
-            'token. Try running "gh auth login" (will list info about ' +
-            'your account) and try this again when that works.',
-          )
-          exit(1)
-        end
-      end
-      s
-    end
-
-    def self.in_repo?
-      s = git_nofail('rev-parse', '--is-inside-work-tree')
-      !s.error? && s.stdout.strip == 'true'
-    end
-
-    def self.repo_root
-      git('rev-parse', '--show-toplevel').stdout.strip
-    end
   end
 end

data/lib/sugarjar/version.rb

@@ -1,3 +1,3 @@
 class SugarJar
-  VERSION = '3.0.0'.freeze
+  VERSION = '4.0.0'.freeze
 end

data/sugarjar.gemspec

@@ -26,6 +26,7 @@ Gem::Specification.new do |spec|
     Dir.glob('extras/*')
 
   spec.add_dependency 'deep_merge'
+  spec.add_dependency 'diffy'
   spec.add_dependency 'mixlib-log'
   spec.add_dependency 'mixlib-shellout'
   spec.add_dependency 'pastel'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sugarjar
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Phil Dibowitz
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-08 00:00:00.000000000 Z
+date: 2026-08-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: deep_merge
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: diffy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: mixlib-log
   requirement: !ruby/object:Gem::Requirement
@@ -98,12 +112,16 @@ files:
 - lib/sugarjar/commands/checks.rb
 - lib/sugarjar/commands/debuginfo.rb
 - lib/sugarjar/commands/feature.rb
+- lib/sugarjar/commands/modernize_config.rb
 - lib/sugarjar/commands/pullsuggestions.rb
 - lib/sugarjar/commands/push.rb
 - lib/sugarjar/commands/smartclone.rb
 - lib/sugarjar/commands/smartpullrequest.rb
 - lib/sugarjar/commands/up.rb
 - lib/sugarjar/config.rb
+- lib/sugarjar/forge.rb
+- lib/sugarjar/git.rb
+- lib/sugarjar/help.rb
 - lib/sugarjar/log.rb
 - lib/sugarjar/repoconfig.rb
 - lib/sugarjar/util.rb