sugarjar 1.1.3 → 2.0.1

data/README.md

@@ -4,17 +4,8 @@
 [![Unittest](https://github.com/jaymzh/sugarjar/workflows/Unittests/badge.svg)](https://github.com/jaymzh/sugarjar/actions?query=workflow%3AUnittests)
 [![DCO](https://github.com/jaymzh/sugarjar/workflows/DCO%20Check/badge.svg)](https://github.com/jaymzh/sugarjar/actions?query=workflow%3A%22DCO+Check%22)
 
-> [!IMPORTANT]
-> As this was meant to replace arc/jf, which has now been open-sourced as
-> [Sapling](https://sapling-scm.com/), I highly recommend taking a look at that!
->
-> Sapling is a great tool and solves a variety of problems SugarJar will never
-> be able to. However, it is a bigger workflow change, so existing SJ users
-> may choose to stick with this. Similarly some workflows may not be suitable
-> for Sapling. I still plan to maintain and develop SugarJar for the time being.
-
-Welcome to SugarJar - a git/github helper. It needs one of the GitHub CLI's:
-either [gh](https://cli.github.com/) or the older [hub](https://hub.github.com/).
+Welcome to SugarJar - a git/github helper. The only requirements are Ruby,
+`git`, and [gh](https://cli.github.com/).
 
 SugarJar is inspired by [arcanist](https://github.com/phacility/arcanist), and
 its replacement at Facebook, JellyFish. Many of the features they provide for
@@ -27,39 +18,30 @@ If you miss Mondrian or Phabricator - this is the tool for you!
 
 If you don't, there's a ton of useful stuff for everyone!
 
-## Installation
-
-Sugarjar is packaged in a variety of Linux distributions - see if it's on the
-list here, and if so, use your package manager (or `gem`) to install it:
-
-[![Packaging status](https://repology.org/badge/vertical-allrepos/sugarjar.svg?exclude_unsupported=1)](https://repology.org/project/sugarjar/versions)
-
-If you are using a Linux distribution version that is end-of-life'd, click the
-above image, it'll take you to a page that lists unsupported distro versions
-as well (they'll have older SugarJar, but they'll probably still have some
-version).
-
-Ubuntu users, Ubuntu versions prior to 24.x cannot be updated, so if you're on
-an older Ubuntu please use [this
-PPA](https://launchpad.net/~michel-slm/+archive/ubuntu/sugarjar) from our
-Ubuntu package maintainer.
-
-For MacOS users, we recommend using Homebrew - SugarJar is now in Homebrew Core.
-
-NOTE: If you previously used our custom Homebrew tap, you should remove and
-untap it:
-
-```shell
-homebrew uninstall sugarjar
-homebrew untap jaymzh/sugarjar
-```
-
-Then you can install the core version (`brew install sugarjar`).
-
-Finally, if none of those work for you, you can clone this repo and run it
-directly from there.
-
-## Auto cleanup squash-merged branches
+Jump to what you're most interested in:
+
+* [Common Use-cases](#common-use-cases)
+   * [Auto Cleanup Squash-merged branches](#auto-cleanup-squash-merged-branches)
+   * [Smarter clones and remotes](#smarter-clones-and-remotes)
+   * [Work with stacked branches more easily](#work-with-stacked-branches-more-easily)
+   * [Creating Stacked PRs with subfeatures](#creating-stacked-prs-with-subfeatures)
+   * [Have a better lint/unittest experience!](#have-a-better-lintunittest-experience)
+   * [Better push defaults](#better-push-defaults)
+   * [Cleaning up your own history](#cleaning-up-your-own-history)
+   * [Better feature branches](#better-feature-branches)
+   * [Smartlog](#smartlog)
+   * [Pulling in suggestions from the web](#pulling-in-suggestions-from-the-web)
+   * [And more!](#and-more)
+* [Installation](#installation)
+* [Configuration](#configuration)
+* [Repository Configuration](#repository-configuration)
+   * [Commit Templates](#commit-templates)
+* [Enterprise GitHub](#enterprise-github)
+* [FAQ](#faq)
+
+## Common Use-cases
+
+### Auto cleanup squash-merged branches
 
 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"
@@ -71,9 +53,7 @@ forces the deletion.
 Enter `sj bclean` - it determines if the contents of your branch has been merge
 and safely deletes if so.
 
-``` shell
-sj bclean
-```
+![bclean screenshot](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**.
 
@@ -83,44 +63,32 @@ You can pass it a branch if you'd like (it defaults to the branch you're on):
 But it gets better! You can use `sj bcleanall` to remove all branches that have
 been merged:
 
-```shell
-$ git branch
-* argparse
-  master
-  feature
-  hubhost
-$ git bcleanall
-Skipping branch argparse - there are unmerged commits
-Reaped branch feature
-Reaped branch hubhost
-```
+![bcleanall screenshot](https://github.com/jaymzh/sugarjar/blob/main/images/bcleanall.png)
 
-## Smarter clones and remotes
+### Smarter clones and remotes
 
 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:
 
-```shell
-sj smartclone jaymzh/sugarjar
-```
+![smartclone screenshot](https://github.com/jaymzh/sugarjar/blob/main/images/sclone.png)
 
-(also `sj sclone`)
+`sj` accepts both `smartclone` and `sclone` for this command.
 
 This will:
 
-* Make a fork of the repo, if you don't already have one
+* Fork the repo to your personal org (if you don't already have a fork)
 * 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.
 
-Like `git clone`, `sj sclone` will accept an additional argument as the
+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.
 
-## Work with stacked branches more easily
+### Work with stacked branches more easily
 
 It's important to break changes into reviewable chunks, but working with
 stacked branches can be confusing. SugarJar provides several tools to make this
@@ -130,122 +98,75 @@ First, and foremost, is `feature` and `subfeature`. Regardless of stacking, the
 way to create a new feature bracnh with sugarjar is with `sj feature` (or `sj
 f` for short):
 
-```shell
-$ sj feature mynewthing
-Created feature branch mynewthing based on origin/main
-```
+![feature screenshot](https://github.com/jaymzh/sugarjar/blob/main/images/feature.png)
 
-A "feature" in SugarJar parliance just means that the branch is always created
-from "most_main" - this is usually "upstream/main", but SJ will figure out
-which remote is the "upstream", even if it's "origin", and then will determine
-the primary branch ("main" or for older repos "master"). It's also smart enough
+A "feature" in SugarJar parlance just means that the branch is always created
+from "most main" - this is usually `upstream/main`, but SJ will figure out
+which remote is the "upstream", even if it's `origin`, and then will determine
+the primary branch (`main` or for older repos `master`). It's also smart enough
 to fetch that remote first to make sure you're working on the latest HEAD.
 
-When you want to create a stacked PR, you can create "subfeature", which, at
+When you want to create a stacked PR, you can create `subfeature`, which, at
 its core is just a branch created from the current branch:
 
-```shell
-$ sj subfeature dependentnewthing
-Created feature branch dependentnewthing based on mynewthing
-```
+![subfeature screenshot](https://github.com/jaymzh/sugarjar/blob/main/images/subfeature.png)
 
 If you create branches like this then sugarjar can now make several things
 much easier:
 
 * `sj up` will rebase intelligently
 * After an `sj bclean` of a branch earlier in the tree, `sj up` will update
-  the tracked branch to "most_main"
+  the tracked branch to "most main"
 
 There are two commands that will show you the state of your stacked branches:
 
 * `sj binfo` - shows the current branch and its ancestors up to your primary branch
-* `sj smartlist` (aka `sj sl`) - shows you the whole tree.
+* `sj smartlog` (aka `sj sl`) - shows you the whole tree.
 
-To continue with the example above, my `smartlist` might look like:
+To continue with the example above, my `smartlog` might look like:
 
-```text
-$ sj sl
-* 59c0522 (HEAD -> dependentnewthing) anothertest
-* 6ebaa28 (mynewthing) test
-o 7a0ffd0 (tag: v1.1.2, origin/main, origin/HEAD, main) Version bump (#160)
-```
+![subfeature-smartlog screenshot](https://github.com/jaymzh/sugarjar/blob/main/images/subfeature-smartlog.png)
 
-This is simple. Now lets make a different feature stack:
+As you can see, `mynewthing` is derived from `main`, and `dependentnewthing` is
+derived from `mynewthing`.
 
-```text
-$ sj feature anotherfeature
-Created feature branch anotherfeature based on origin/main
-# do stuff
-$ sj subfeature dependent2
-Created feature branch dependent2 based on anotherfeature
-# do stuff
-```
+Now lets make a different feature stack:
 
-The `smartlist` will now show us this tree, and it's a bit more interesting:
+![subfeature-part2 screenshot](https://github.com/jaymzh/sugarjar/blob/main/images/subfeature-part2.png)
 
-```text
-$ sj sl
-* af6f143 (HEAD -> dependent2) morestuff
-* 028c7f4 (anotherfeature) stuff
-| * 59c0522 (dependentnewthing) anothertest
-| * 6ebaa28 (mynewthing) test
-|/
-o 7a0ffd0 (tag: v1.1.2, origin/main, origin/HEAD, main) Version bump (#160)
-```
+The `smartlog` will now show us this tree, and it's a bit more interesting:
 
-Now, what happens if I make a change to `mynewthing`?
+![subfeature-part2-smartlog screenshot](https://github.com/jaymzh/sugarjar/blob/main/images/subfeature-part2-smartlog.png)
 
-```text
-$ sj co mynewthing
-Switched to branch 'mynewthing'
-Your branch is ahead of 'origin/main' by 1 commit.
-  (use "git push" to publish your local commits)
-$ echo 'randomchange' >> README.md
-$ git commit -a -m change
-[mynewthing d33e082] change
- 1 file changed, 1 insertion(+)
-$ sj sl
-* d33e082 (HEAD -> mynewthing) change
-| * af6f143 (dependent2) morestuff
-| * 028c7f4 (anotherfeature) stuff
-| | * 59c0522 (dependentnewthing) anothertest
-| |/
-|/|
-* | 6ebaa28 test
-|/
-o 7a0ffd0 (tag: v1.1.2, origin/main, origin/HEAD, main) Version bump (#160)
-```
+Here we can see from `main`, we have two branches: one going to `mynewthing`
+and one going to `anotherfeature`. Each of those has their own dependent branch
+on top.
+
+Now, what happens if I make a change to `mynewthing` (the bottom of the first stack)?
+
+![subfeature-part3 screenshot](https://github.com/jaymzh/sugarjar/blob/main/images/subfeature-part3.png)
 
 We can see here now that `dependentnewthing`, is based off a commit that _used_
-to be `mynewthing`, but `mynewthing` has moved. But SugarJar will handle this
-all correctly when we ask it to update the branch:
+to be `mynewthing` (`5086ee`), but `mynewthing` has moved. Both `mynewthing`
+and `dependentnewthing` are derived from `5086ee` (the old `mynewthing`), but
+`dependentnewthing` isn't (yet) based on the current `mynewthing`. But SugarJar
+will handle this all correctly when we ask it to update the branch:
 
-```text
-$ sj co dependentnewthing
-Switched to branch 'dependentnewthing'
-Your branch and 'mynewthing' have diverged,
-and have 1 and 1 different commits each, respectively.
-  (use "git pull" if you want to integrate the remote branch with yours)
-$ sj up
-dependentnewthing rebased on mynewthing
-$ sj sl
-* 93ed585 (HEAD -> dependentnewthing) anothertest
-* d33e082 (mynewthing) change
-* 6ebaa28 test
-| * af6f143 (dependent2) morestuff
-| * 028c7f4 (anotherfeature) stuff
-|/
-o 7a0ffd0 (tag: v1.1.2, origin/main, origin/HEAD, main) Version bump (#160)
-```
+![subfeature-part3-rebase screenshot](https://github.com/jaymzh/sugarjar/blob/main/images/subfeature-part3-rebase.png)
+
+Here we see that SugarJar knew that `dependentnewthing` should be rebased onto
+`mynewthing`, and it did the right thing - from main there's still the
+`50806ee` _and_ the new additional change which are now both part of the
+`mynewthing` branch, and `dependentnewthing` is based on that branch, this
+including all 3 commits in the right order.
 
 Now, lets say that `mynewthing` gets merged and we use `bclean` to clean it all
 up, what happens then?
 
-```text
-$ sj up
-The brach we were tracking is gone, resetting tracking to origin/main
-dependentnewthing rebased on origin/main
-```
+![subfeature-detect-missing-base screenshot](https://github.com/jaymzh/sugarjar/blob/main/images/subfeature-detect-missing-base.png)
+
+SugarJar detects that branch is gone and thus this branch should now be based
+on the upstream main branch!
 
 ### Creating Stacked PRs with subfeatures
 
@@ -261,12 +182,12 @@ It looks like this is a subfeature, would you like to base this PR on mynewthing
 ...
 ```
 
-## Have a better lint/unittest experience!
+### Have a better lint/unittest experience!
 
 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)
-and Markdownlint "on_push". If those fail, it lets you know and doesn't push.
+and Markdownlint `on_push`. If those fail, it lets you know and doesn't push.
 
 You can configure SugarJar to tell it how to run both lints and unittests for
 a given repo and if one or both should be run prior to pushing.
@@ -274,31 +195,31 @@ a given repo and if one or both should be run prior to pushing.
 The details on the config file format is below, but we provide three commands:
 
 ```shell
-git lint
+sj lint
 ```
 
 Run all linters.
 
 ```shell
-git unit
+sj unit
 ```
 
 Run all unittests.
 
 ```shell
-git smartpush # or spush
+sj smartpush # or spush
 ```
 
 Run configured push-time actions (nothing, lint, unit, both), and do not
 push if any of them fail.
 
-## Better push defaults
+### Better push defaults
 
 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.
 
-## Cleaning up your own history
+### Cleaning up your own history
 
 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
@@ -318,7 +239,7 @@ 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!
 
-## Better feature branches
+### Better feature branches
 
 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
@@ -347,14 +268,14 @@ use branch-based workflows and branches need to be prefixed with 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`.
 
-## Smartlog
+### Smartlog
 
 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/smartlog.png)
+![smartlog screenshot](https://github.com/jaymzh/sugarjar/blob/main/images/smartlog.png)
 
-## Pulling in suggestions from the web
+### Pulling in suggestions from the web
 
 When someone 'suggests' a change in the GitHub WebUI, once you choose to commit
 them, your origin and local branches are no longer in-sync. The
@@ -363,44 +284,31 @@ 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.
 
-## And more!
+### And more!
 
 See `sj help` for more commands!
 
-## Using SugarJar as a git wrapper
+## Installation
 
-SugarJar, by default, will pass any command it doesn't know straight to `hub`
-(which passes commands **it** doesn't know to `git`). If you have configured
-SugarJar to use `gh` instead of `hub`, then it will pass commands straight to
-`git` since `gh` doesn't act as a `git` wrapper.
+Sugarjar is packaged in a variety of Linux distributions - see if it's on the
+list here, and if so, use your package manager (or `gem`) to install it:
 
-As such you can alias it to `git` and just have a super-git.
+[![Packaging status](https://repology.org/badge/vertical-allrepos/sugarjar.svg?exclude_unsupported=1)](https://repology.org/project/sugarjar/versions)
 
-```shell
-$ alias git=sj
-$ git config -l | grep color
-color.diff=auto
-color.status=auto
-color.branch=auto
-color.branch.current=yellow reverse
-color.branch.local=yellow
-color.branch.remote=green
-$ git br
-* dependent-feature 44cf9e2 Lint/gemspec cleanups
-  master            44cf9e2 Lint/gemspec cleanups
-  test-branch       44cf9e2 Lint/gemspec cleanups
-  test1             c808eae [ahead 1] test1
-  test2             e545b41 test2
-  test2.1           c1831b3 test2.1
-  test3             e451865 test3
-```
+If you are using a Linux distribution version that is end-of-life'd, click the
+above image, it'll take you to a page that lists unsupported distro versions
+as well (they'll have older SugarJar, but they'll probably still have some
+version).
+
+Ubuntu users, Ubuntu versions prior to 24.x cannot be updated, so if you're on
+an older Ubuntu please use [this
+PPA](https://launchpad.net/~michel-slm/+archive/ubuntu/sugarjar) from our
+Ubuntu package maintainer.
 
-It's for this reason that SugarJar doesn't have conflicting command names. You
-can turn off fallthru by setting `fallthru: false` in your config.
+For MacOS users, we recommend using Homebrew - SugarJar is now in Homebrew Core.
 
-The only command we "override" is `version`, in which case we not only print
-our version, but also call `hub version` which prints its version and calls
-`git version` too!
+Finally, if none of those work for you, you can clone this repo and run it
+directly from there.
 
 ## Configuration
 
@@ -408,59 +316,32 @@ Sugarjar will read in both a system-level config file
 (`/etc/sugarjar/config.yaml`) and a user-level config file
 `~/.config/sugarjar/config.yaml`, if they exist. Anything in the user config
 will override the system config, and command-line options override both. The
-yaml file is a straight key-value pair of options without their '--'. For
-example:
+yaml file is a straight key-value pair of options without their '--'.
 
-```yaml
-log_level: debug
-github_user: jaymzh
-```
+See [examples/sample_config.yaml](examples/sample_config.yaml) for an example
+configuration file.
 
 In addition, the environment variable `SUGARJAR_LOGLEVEL` can be defined to set
 a log level. This is primarily used as a way to turn debug on earlier in order to
 troubleshoot configuration parsing.
 
-## Repository Configuration
-
-Sugarjar looks for a `.sugarjar.yaml` in the root of the repository to tell it
-how to handle repo-specific things. Currently there options are:
-
-* `lint` - A list of scripts to run on `sj lint`. These should be linters like
-  rubocop or pyflake. Linters will be run from the root of the repo.
-* `lint_list_cmd` - A command to run which will print out linters to run, one
-  per line. Takes precedence over `lint`. The command (and the resulting
-  linters) will be run from the root of the repo.
-* `unit` - A list of scripts to run on `sj unit`. These should be unittest
-  runners like rspec or pyunit. Test will be run from the root of the repo.
-* `unit_list_cmd` - A command to run which will print out the unit tests to
-  run, one more line. Takes precedence over `unit`. The command (and the
-  resulting unit tests) will be run from the root of the repo.
-* `on_push` - A list of types (`lint`, `unit`) of checks to run before pushing.
-  It is highly recommended this is only `lint`. The goal here is to allow for
-  the user to get quick stylistic feedback before pushing their branch to avoid
-  the push-fix-push-fix loop.
-* `commit_template` - A path to a commit template to set in the `commit.template`
-  git config for this repo. Should be either a fully-qualified path, or a path
-  relative to the repo root.
-* `include_from` - This will read an additional repoconfig file and merge it
-  into the one being read. The value should be relative to the root of the
-  repo. This will not error if the file does not exist, it is intended for
-  organizations to allow users to optionally extend a default repo config.
-* `overwrite_from` - Same as `include_from`, but completely overwrites the
-  base configuration if the file is found.
-
-Example configuration:
+Deprecated fields will cause a warning, but you can suppress that warning by
+defining `ignore_deprecated_options`, for example:
 
 ```yaml
-lint:
-  - scripts/lint
-unit:
-  - scripts/unit
-on_push:
-  - lint
-commit_template: .commit-template.txt
+old_option: foo
+ignore_deprecated_options:
+  - old_options
 ```
 
+## Repository Configuration
+
+Sugarjar looks for a `.sugarjar.yaml` in the root of the repository to tell it
+how to handle repo-specific things. See
+[examples/sample_repoconfig.yaml](examples/sample_repoconfig.yaml) for an
+example configuration that walks through all valid repo configurations in
+detail.
+
 ### Commit Templates
 
 While GitHub provides a way to specify a pull-request template by putting the
@@ -471,33 +352,27 @@ prone, so this setting will automatically set this up for each developer.
 
 ## Enterprise GitHub
 
-Like `hub`, SugarJar supports GitHub Enterprise. In fact, we provide extra
+Like `gh`, SugarJar supports GitHub Enterprise. In fact, we provide extra
 features just for it.
 
-We recommend the global or user config specify the `github_host`. However, most
-users will also have a few repos from upstream so always specifying a
-`github_host` is sub-optimal.
+You can set `github_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.
 
-So, when you overwrite the `github_host` on the command line, we go ahead and
-set the `hub.host` git config in that single repo so that it'll "just work"
-from there on out.
+So, for example you might have:
 
-In other words, assuming your global SJ config has `github_host:
-github.sample.com`, and the you clone sugarjar with:
-
-```shell
-sj clone jaymzh/sugarjar --github-host githuh.com
+```yaml
+github_host: gh.sample.com
 ```
 
-We will add the `hub.host` to the `sugarjar` clone so that future `hub` or `sj`
-commands work without needing to specify..
+In your `~/.config/sugarjar/config.yaml`, but if the `.sugarjar.yaml` in your
+repo has:
 
-## Choosing a GitHub CLI
+```yaml
+github_host: github.com
+```
 
-SugarJar will use `gh` if it is available or otherwise fall back to `hub`. You
-can override this by specifying `--github-cli` on the command line or setting
-`github_cli` to either `gh` or `hub` (it defaults to `auto`) in your
-configuration.
+Then we will configure `gh` to talk to github.com when in that repo.
 
 ## FAQ
 
@@ -509,15 +384,6 @@ possible options that where there and not taken and tried to find one I could
 make an appropriate name out of. Since this utility adds lots of sugar to git
 and github, it seemed appropriate.
 
-**Why did you originally use `hub` instead of the newer `gh` CLI?**
-
-When I originally wrote SugarJar, `gh` was in early development, and `hub` had
-many more features. In addition, I wrote SugarJar to be a wrapper for git/hub,
-and `hub` allows this but `gh` does not.
-
-When `gh` matured, we added experimental `gh` support in 0.0.11, and switched the
-default to prefer `gh` in 1.0.0.
-
 **I'd like to package SugarJar for my favorite distro/OS, is that OK?**
 
 Of course! But I'd appreciate you emailing me to give me a heads up. Doing so
@@ -534,3 +400,15 @@ it on Windows, but I'll happily accept patches for Windows compatibility.
 If the package for your OS/distro didn't set it up manually, you should find
 that `sugarjar_completion.bash` is included in the package, and you can simply
 source that in your dotfiles, assuming you are using bash.
+
+**What happens now that Sapling is released?**
+
+SugarJar isn't going anywhere anytime soon. This was meant to replace arc/jf,
+which has now been open-sourced as [Sapling](https://sapling-scm.com/), so I
+highly recommend taking a look at that!
+
+Sapling is a great tool and solves a variety of problems SugarJar will never be
+able to. However, it is a significant workflow change, that won't be
+appropriate for all users or use-cases. Similarly there are workflows and tools
+that Sapling breaks. So worry not, SugarJar will continue to be maintained and
+developed.