sugarjar 3.0.1 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a412f3091d9ce81db841098d46c0b74f5ccf210e7f62916db5f36f68d4f9218f
-  data.tar.gz: db6f60757390c2e8decf11cada9a423f4d61284304e9db43ef4785636f621fd3
+  metadata.gz: d8993339f3317f275721220d1b548fa4253180783483c4ea0d1a69080b25b6f1
+  data.tar.gz: 05ca92916f85edd2e1f5657aebc9e8fa50404a7ab22c973bc22bcae2bd932928
 SHA512:
-  metadata.gz: 550d6c2792dd3b800f8fcbb3ab0d34019ba59ae09596988fc31c92452270d220c6e0a8feead9f767750f2fb529f2e0c60421a8e5756bb5c80974a7329142404b
-  data.tar.gz: b723f16e4a2640777ebc8496afa635ff146f0a5de8e0359213aa0824e43b236a312fd199c5ddea047ff5acba604848e48ea94d9716a80ff4d280210b6dc32c83
+  metadata.gz: 1d1317871412a3a251cf5c5f5b456db154dc672cdbacb7475d8486ac57c8ec87ad9b5ff5daf5814bd5e9ad94b0b987f1a072c6635d713061c9d297fe0edea460
+  data.tar.gz: b70c9c903409db5c277752b746e6b108568434c6d95b61a7d3bb2d3fb483fc66966d14ade23bee067805212ad28d485ca928b2441d67d06b36b58468ed982e21

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # SugarJar Changelog
 
+## 4.0.0 (2026-08-09)
+
+* Rework config file format to be more friendly to working with multiple forges
+* Add `modernizeconfig` command to help users migrate to new config file format
+* Various improvements to gitlab compatibility
+* Fix bugs around repo name detection when directory name doesn't match
+* Revamp `help` to be easier to read and navigate
+* Add support for Forgejo/Codeberg forges
+* Update repoconfig format to allow specifying names for checks
+
 ## 3.0.1 (2026-06-19)
 
 * Update tests for more resiliency in various package-building environments

data/README.md

@@ -30,6 +30,10 @@ If you don't, there's a ton of useful stuff for everyone!
 
 Jump to what you're most interested in:
 
+> [!NOTE]
+> There is a new 'modernizeconfig' option to automatically convert your
+> config for the significant changes in 4.x.
+
 * [Common Use-cases](#common-use-cases)
    * [Auto Cleanup Squash-merged branches](#auto-cleanup-squash-merged-branches)
    * [Smarter clones and remotes](#smarter-clones-and-remotes)
@@ -59,12 +63,16 @@ Jump to what you're most interested in:
 
 ### Auto cleanup squash-merged branches
 
+<details>
+
+<summary>Clean-up squash-merged PRs safely and easily</summary>
+
 It is common for a PR to go back and forth with a variety of nits, lint fixes,
 typos, etc. that can muddy history. So many projects will "squash and merge"
-when they accept a pull request. However, that means `git branch -d <branch>`
-doesn't work. Git will tell you the branch isn't fully merged. You can, of
-course `git branch -D <branch>`, but that does no safety checks at all, it
-forces the deletion.
+when they accept a pull request. However, that means `git branch -d
+BRANCH` doesn't work. Git will tell you the branch isn't fully merged.
+You can, of course `git branch -D BRANCH`, but that does no safety
+checks at all, it forces the deletion.
 
 Enter `sj lbclean` - it determines if the contents of your branch has been merge
 and safely deletes if so. (Note: `lbclean` stands for "local branch clean", and
@@ -78,7 +86,7 @@ https://github.com/jaymzh/sugarjar/blob/main/images/bclean.png
 Will delete a branch, if it has been merged, **even if it was squash-merged**.
 
 You can pass it a branch if you'd like (it defaults to the branch you're on):
-`sj bclean <branch>`.
+`sj bclean BRANCH`.
 
 But it gets better! You can use `sj bcleanall` to remove all branches that have
 been merged:
@@ -100,9 +108,14 @@ There is even `sj gbclean` ("global branch clean") (and `sj gbcleanall`) which
 will do both the local and remote cleaning.
 
 *NOTE*: Remote branch cleaning is still experimental, use with caution!
+</details>
 
 ### Smarter clones and remotes
 
+<details>
+
+<summary>Fork, clone, and add the upstream remote automatically</summary>
+
 There's a pattern to every new repo we want to contribute to. First we fork,
 then we clone the fork, then we add a remote of the upstream repo. It's
 monotonous. SugarJar does this for you:
@@ -120,18 +133,35 @@ This will:
 * Clone your fork
 * Add the original as an 'upstream' remote
 
-Note that it takes short names for repos. No need to specify a full URL,
-just a $org/$repo.
+Note that if you pass in a full-formed URL (like
+`git@github.com:chef/omnibus-toolchain.git`), SugarJar will infer the host and
+the forge type (gitub, gitlab, etc.). However, it does accept short names for
+repos ($org/$repo) - however, for cloning, since there is no repo yet for
+SugarJar to determine the forge from, you will need either to specify
+`--default-forge-host`, or have `default_forge_host` set in your config file.
 
 Like `git clone`, `sj smartclone` will accept an additional argument as the
 destination directory to clone to. It will also pass any other unknown options
 to `git clone` under the hood.
 
 If you don't work with fork-based workflows, you can set `use_forks: false`
-in your config, or pass in `--no-use-forks` to `sj sclone`.
+in your config for the right host:
+
+```yaml
+host_configs:
+  default:
+    use_forks: false
+```
+
+See [Configuration](#Configuration) for more details on the config file.
+</details>
 
 ### Work with stacked branches more easily
 
+<details>
+
+<summary>Create and manage stacked/dependent branches easily</summary>
+
 It's important to break changes into reviewable chunks, but working with
 stacked branches can be confusing. SugarJar provides several tools to make this
 easier.
@@ -227,9 +257,14 @@ https://github.com/jaymzh/sugarjar/blob/main/images/subfeature-detect-missing-ba
 
 SugarJar detects that branch is gone and thus this branch should now be based
 on the upstream main branch!
+</details>
 
 ### Creating Stacked PRs with subfeatures
 
+<details>
+
+<summary>Automatically base PRs for subfeatures on their parent branch</summary>
+
 When dependent branches are created with `subfeature`, when you create a PR,
 SugarJar will automatically set the 'base' of the PR to the parent branch. By
 default it'll prompt you about this, but you can set `pr_autostack` to `true`
@@ -242,8 +277,14 @@ It looks like this is a subfeature, would you like to base this PR on mynewthing
 ...
 ```
 
+</details>
+
 ### Smart release branch handling
 
+<details>
+
+<summary>Configure and protect long-lived release branches</summary>
+
 You can tell sugar what release branches exist, and it will intelligently
 handle them. So of you specify, in your repoconfig:
 
@@ -259,9 +300,14 @@ Then:
   to `upstream/v2-branch` (or `origin/v2-branch` as appropriate)
 * `sj lbclean`/`sj lbcleanall` (of all varieties) will never reap release
   branches
+</details>
 
 ### Have a better lint/unittest experience!
 
+<details>
+
+<summary>Run lint and unittests automatically before pushing</summary>
+
 Ever made a PR, only to find out later that it failed tests because of some
 small lint issue? Not anymore! SJ can be configured to run things before
 pushing. For example,in the SugarJar repo, we have it run Rubocop (ruby lint)
@@ -290,15 +336,25 @@ sj smartpush # or spush
 
 Run configured push-time actions (nothing, lint, unit, both), and do not
 push if any of them fail.
+</details>
 
 ### Better push defaults
 
+<details>
+
+<summary>Smart defaults for `smartpush`</summary>
+
 In addition to running pre-push tests for you `smartpush` also picks smart
 defaults for push. So if you `sj spush` with no arguments, it uses the
 `origin` remote and the same branch name you're on as the remote branch.
+</details>
 
 ### Cleaning up your own history
 
+<details>
+
+<summary>Safely amend commits and force-push with `amend`/`fpush`</summary>
+
 Perhaps you contribute to a project that prefers to use merge commits, so you
 like to clean up your own history. This is often difficult to get right - a
 combination of rebases, amends and force pushes. We provide two commands here
@@ -316,9 +372,14 @@ sure you're up-to-date with the remote before forcing the push. But man that
 command is a mouthful! Enter `sj fpush`. It has all the smarts of `sj
 smartpush` (runs configured pre-push actions), but adds `--force-with-lease` to
 the command!
+</details>
 
 ### Better feature branches
 
+<details>
+
+<summary>Create feature branches with the right base and prefix</summary>
+
 When you want to start a new feature, you want to start developing against
 latest. That's why `sj feature` defaults to creating a branch against what we
 call "most master". That is, `upstream/master` if it exists, otherwise
@@ -347,17 +408,36 @@ e.g. `$USER/`.
 For example, if your prefix was `user/`, then `sj feature foo` would create
 `user/foo`, and `sj co foo` would switch to `user/foo`.
 
+Here's an example:
+
+```yaml
+host_configs:
+  default:
+    feature_prefix: "jsmith/"
+```
+
+</details>
+
 ### Smartlog
 
+<details>
+
+<summary>Visualize your branch tree</summary>
+
 Smartlog will show you a tree diagram of your branches! Simply run `sj
 smartlog` or `sj sl` for short.
 
 ![smartlog screenshot](
 https://github.com/jaymzh/sugarjar/blob/main/images/smartlog.png
 )
+</details>
 
 ### Sync work across workstations
 
+<details>
+
+<summary>Keep branches in sync across multiple machines</summary>
+
 If you work on multiple workstations, keeping your branches in-sync can be a
 pain. SugarJar provides `sync` to help with this.
 
@@ -370,19 +450,50 @@ from `origin/foo`. If you have local changes, that are not already on
 
 It's very similar to `sj up`, but instead of rebasing on top of the tracking
 branch, it rebases on top of the push target branch.
+</details>
 
 ### Pulling in suggestions from the web
 
+<details>
+
+<summary>Merge in GitHub/GitLab suggested changes</summary>
+
 When someone 'suggests' a change in the GH/GL WebUI, once you choose to commit
 them, your origin and local branches are no longer in-sync. The
 `pullsuggestions` command will attempt to merge in any remote commits to your
 local branch. This command will show a diff and ask for confirmation before
 attempting the merge and  - if allowed to continue - will use a fast-forward
 merge.
+</details>
+
+### Modernize your config
+
+<details>
+
+<summary>Convert your old config to the new `host_configs` format</summary>
+
+In 4.0, we significantly revamped how the configuration works, adding the new
+`host_configs` section, and deprecating or moving many top-level configs. In
+order to make this transition easier, there is now a `modernizeconfig` command
+to convert it for you!
+
+```shell
+sj modernizeconfig ~/.config/sugarjar/config.yml
+```
+
+This will generate a new config for you, show you a diff, and offer to either
+update the existing file, or save it off the side for you.
+
+</details>
 
 ### And more!
 
+<details>
+
+<summary>There's even more than this!</summary>
+
 See `sj help` for more commands!
+</details>
 
 ## Installation
 
@@ -454,24 +565,18 @@ prone, so this setting will automatically set this up for each developer.
 Like `gh` and `glab`, SugarJar supports Enterprise versions of GitHub and
 GitLab. In fact, we provide extra features just for it.
 
-In most cases, when using `sj smartclone`, pass in `--forge-host`, and
-that's about all you need, everything else should be handlded automagically.
-
-However, you can set `forge_host` in your global or user config, but since most
-users will also have a few opensource repos, you can override it in the
-Repository Config as well.
+By default, SugarJar will pick up the appropriate information from the repo
+itself, so the only real interesting part is `smartclone`. In most cases,
+SugarJar will automatically determine the proper forge-host based on the URL
+you pass in. However, if you use short names ("repo/org" or
+"company/repo/org"), then you can either pass in `--default-forge-host`, or, if
+you want to always default to a given host, you can set a top-level
+`default_forge_host` in your SugarJar config:
 
 So, for example you might have:
 
 ```yaml
-forge_host: gh.sample.com
-```
-
-In your `~/.config/sugarjar/config.yaml`, but if the `.sugarjar.yaml` in your
-repo has:
-
-```yaml
-forge_host: github.com
+default_forge_host: gh.sample.com
 ```
 
 ## FAQ

data/bin/sj

@@ -5,6 +5,7 @@ require 'optparse'
 require 'mixlib/shellout'
 require_relative '../lib/sugarjar/commands'
 require_relative '../lib/sugarjar/config'
+require_relative '../lib/sugarjar/help'
 require_relative '../lib/sugarjar/log'
 require_relative '../lib/sugarjar/util'
 require_relative '../lib/sugarjar/version'
@@ -23,6 +24,7 @@ if ENV['SUGARJAR_LOGLEVEL']
   options['log_level'] = SugarJar::Log.level = ENV['SUGARJAR_LOGLEVEL'].to_sym
 end
 
+options['_cli_overrides'] = {}
 parser = OptionParser.new do |opts|
   opts.banner = 'Usage: sj <command> [<args>] [<options>]'
 
@@ -31,39 +33,39 @@ parser = OptionParser.new do |opts|
   opts.separator ''
   opts.separator 'OPTIONS:'
 
-  opts.on('--feature-prefix', 'Prefix to use for feature branches') do |prefix|
-    options['feature_prefix'] = prefix
-  end
-
   opts.on(
-    '--forge-host HOST',
-    '--github-host HOST',
-    'The host of your forge (github, gitlab, etc.). Generally only needed' +
-    ' when cloning (smartclone), as we can usually figure out from within' +
-    ' a cloned repo. Currently accepts --github-host for backwards' +
-    ' compatibility.',
+    '--default-forge-host HOST',
+    'The default host of your forge (github, gitlab, etc.) when it cannot ' +
+    'be determined automatically. In nearly every case SJ will ' +
+    'automatically determine this. However, for `smartclone`, if ' +
+    'you use shortnames (e.g. org/repo) that do not contain a host, this ' +
+    'is the default to assume. Most useful in your config file when set ' +
+    'to your most comomn forge host (e.g. github.com)',
   ) do |host|
-    options['forge_host'] = host
+    options['default_forge_host'] = host
   end
 
-  opts.on('--forge-type TYPE', 'Forge type: github, gitlab') do |type|
-    options['forge_type'] = type
+  opts.on(
+    '--feature-prefix PREFIX',
+    'Bypass the config and just use PREFIX.',
+  ) do |prefix|
+    options['_cli_overrides']['feature_prefix'] = prefix
   end
 
   opts.on(
-    '--github-user USER',
-    'User for github repos, unless specified in the repoconfig.' +
-    ' Defaults to your local username',
-  ) do |user|
-    options['github_user'] = user
+    '--forge-type TYPE',
+    'GENERALLY NOT NEEDED. In case SJ cannot detect the type of a forge ' +
+    'from the hostname during smartclone. Only available in CLI, not a ' +
+    'config file option. Forge type: github, gitlab.',
+  ) do |type|
+    options['_cli_overrides']['forge_type'] = type
   end
 
   opts.on(
-    '--gitlab-user USER',
-    'User for gitlab repos, unless specified in the repoconfig.' +
-    ' Defaults to your local username',
+    '--forge-user USER',
+    'Bypass the config and just use USER as the forge user.',
   ) do |user|
-    options['gitlab_user'] = user
+    options['_cli_overrides']['user'] = user
   end
 
   opts.on('-h', '--help', 'Print this help message') do
@@ -103,14 +105,6 @@ parser = OptionParser.new do |opts|
     options['pr_autofill'] = autofill
   end
 
-  opts.on(
-    '--[no-]use-forks',
-    'Create (add a remote for) forks, when the organization does not match ' +
-    'the user. [default: true]',
-  ) do |val|
-    options['use_forks'] = val
-  end
-
   opts.on(
     '--fork-name NAME',
     'When forking a repo (in `smartclone`), fork the repo to a different ' +
@@ -138,186 +132,11 @@ parser = OptionParser.new do |opts|
     exit
   end
 
-  # rubocop:disable Layout/HeredocIndentation
-  opts.separator <<COMMANDTEXT
-
-COMMANDS:
-  amend
-              Amend the current commit. Alias for "git commit --amend".
-              Accepts other arguments such as "-a" or files.
-
-  amendq, qamend
-              Same as "amend" but without changing the message. Alias for
-              "git commit --amend --no-edit".
-
-  binfo
-              Verbose information about the current branch.
-
-  br
-              Verbose branch list. An alias for "git branch -v".
-
-  debuginfo
-              Prints out a bunch of version and config information useful for
-              including in bug reports.
-
-  feature, f <branch_name>
-              Create a "feature" branch. It's morally equivalent to
-              "git checkout -b" except it defaults to creating it based on
-              some form of 'master' instead of your current branch. In order
-              of preference it will be upstream/master, origin/master, master,
-              depending upon what remotes are available.
-
-              Note that you can specify "--feature-prefix" (or add
-              "feature_prefix" to your config) 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.
-
-  forcepush, fpush
-              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.
-
-  forcesync, fsync
-              See 'sync' below, but never tries to rebase, always does a
-              hard reset.
-
-  globalbranchclean, gbclean [<branch>] [<remote>]
-              WARNING: EXPERIMENTAL COMMAND.
-
-              Combination of "lbclean" and "rbclean". Cleans up
-              both local and remote branches safely. See those commands for
-              details.
-
-  globalbranchcleanall, gbcleanall [<remote>]
-              WARNING: EXPERIMENTAL COMMAND.
-
-              Safely clean all branches, both local and remote.  See "gbclean"
-              for details.
-
-  lint
-              Run any linters configured in .sugarjar.yaml.
-
-  localbranchclean, lbclean [<branch>]
-              If safe, delete the current branch (or the specified branch).
-              Unlike "git branch -d", lbclean can handle squash-merged branches.
-              Think of it as a smarter "git branch -d".
-
-              Aliased to 'bclean' for backwards compatibility.
-
-  localbranchcleanall, lbcleanall
-              Walk all branches, and try to delete them if it's safe. See
-              "lbclean" for details.
-
-              Aliased to 'bcleanall' for backwards compatibility.
-
-  pullsuggestions, ps
-              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.
-
-  remotebranchclean, rbclean [<branch>] [<remote>]
-              WARNING: EXPERIMENTAL COMMAND.
-
-              Similar to lbclean, 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 rclean" to clean the remote branch with
-              the same name as the local one. Note that you probably want
-              "sclean", 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. So if main contains everything that 2.0-devel and 3.0-devel
-              has, then those branches will be deleted. Use with caution.
-
-  remotebranchcleanall, rbcleanall [<remote>]
-              WARNING: EXPERIMENTAL COMMAND.
-
-              Walk all remote branches, and try to delete them if it's safe. See
-              "rbclean" for details.
-
-  smartclone, sclone <repo> [<dir>]
-              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 \
-                  --forge-type glab --fork-name bar-docs
-
-              Or for GitHub:
-
-                sj sclone bar/docs bar-docs \
-                  --forge-type github --fork-name bar-docs
-
-  smartlog, sl
-              Inspired by Facebook's "sl" extension to Mercurial, this command
-              will show you a tree of all your local branches relative to your
-              upstream.
-
-  smartpullrequest, smartpr, spr
-              A smart wrapper to "hub pull-request" that checks if your repo
-              is dirty before creating the pull request.
-
-  smartpush, spush
-              A smart wrapper to "git push" that runs whatever is defined in
-              "on_push" in .sugarjar.yml, and only pushes if they succeed.
-
-  subfeature, sf <feature>
-              An alias for 'sj feature <feature> <current_branch>'
-
-  sync
-              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`.
-
-  unit
-              Run any unitests configured in .sugarjar.yaml.
-
-  up [<branch>]
-              Rebase the current branch (or specified branch) intelligently.
-              In most causes this will check for a main (or master) branch on
-              upstream, then origin. If a branch explicitly tracks something
-              else, then that will be used, instead.
-
-  upall
-              Same as "up", but for all branches.
-COMMANDTEXT
-
-  # rubocop:enable Layout/HeredocIndentation
+  opts.separator ''
+  opts.separator 'COMMANDS:'
+  opts.separator SugarJar::Help.summary_list
+  opts.separator ''
+  opts.separator "Run 'sj help <command>' for details on a specific command."
 end
 
 extra_opts = []
@@ -369,7 +188,18 @@ SugarJar::Log.debug("Final config: #{options}")
 
 # if the command is help, we don't bother to create the Commands obj
 if subcommand == 'help'
-  puts parser
+  help_target = argv_copy.reject { |x| x.start_with?('-') }[1]
+  if help_target
+    help_text = SugarJar::Help.command_help(help_target)
+    if help_text
+      puts help_text
+    else
+      SugarJar::Log.fatal("No such subcommand: #{help_target}")
+      exit 1
+    end
+  else
+    puts parser
+  end
   exit
 end
 

data/examples/sample_config.yaml

@@ -23,8 +23,14 @@ pr_autostack: true
 # list
 ignore_deprecated_options: [ 'gh_cli' ]
 
-# User to use when cloning new github repos
-github_user: c00ldude
-
-# User to use when cloning new gitlab repos
-gitlab_user: c00ldude
+host_configs:
+  default:
+    use_forks: true
+  github.com:
+    user: c00ldude
+  gitlab.com:
+    user: thisc00ldude
+  gitlab.company.com:
+    user: tsmith
+    use_forks: false
+    feature_prefix: "tsmith/"