sugarjar 1.1.2 → 2.0.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4263a42ebb922645e2e0735c3ca33ad94df880fb01f881b2cacb602d733c533e
-  data.tar.gz: 616fb99c535c491324c1dcc4906b37c8cb424566b62dc64377c61b9a5ef5fd49
+  metadata.gz: a9489ff071d470b3191dd934f1276cacdc8aeeec8b6cd9b892af1d49d01d04db
+  data.tar.gz: 24f37e088410ca5be03df9979aeb31e1996987e2d257767908235bc14903fc92
 SHA512:
-  metadata.gz: 1d918daf7096d1889bf72ee0eca74ef473234ed1ed46e4275418028e9a32c9284b4412ff202a932a3cc43c777bbf55d1455ce8fd8805c965184e4d2bc740e527
-  data.tar.gz: 0657a6629d97623d40f68d0ffe7a3e0522c951d9b22dc0c7b4b918d78eb27b026ab68d347b1c2fa68661536eceef9cbf3de3ee82b4ea4381da2675f1d34b3f2d
+  metadata.gz: d3c891c26d1e120f8957f396353f795d4531a212c2fd85e75626d01d27f9ecd8658743bf77fa9062e65c8f5be3f5b1a0dc4f678852dae55b5b4d1e86bf0e97a8
+  data.tar.gz: bf01b6eb19fe535bdc0752b722afd513f423d4ccbd04694faceb6d53e1575a5686fab1d6bdf29c8bd58590b8f4e714aefad3a4b09e67fd9fac22383fafddf4d4

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
@@ -46,16 +37,6 @@ 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.
 
@@ -123,34 +104,142 @@ to `git clone` under the hood.
 ## Work with stacked branches more easily
 
 It's important to break changes into reviewable chunks, but working with
-stacked branches can be confusing. Enter `binfo` - it gives you a view of your
-current branch all the way up to master. In this example imagine we have a
-branch structure like:
+stacked branches can be confusing. SugarJar provides several tools to make this
+easier.
 
-```text
-                      +- test2.1
-                     /
-master --- test --- test2 --- test3
+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
 ```
 
-This is what `binfo` on test3 looks like:
+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
+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
+its core is just a branch created from the current branch:
 
 ```shell
-$ sj binfo
-* e451865 (HEAD -> test3) test3
-* e545b41 (test2) test2
-* c808eae (test1) test1
-o 44cf9e2 (origin/master, origin/HEAD, master) Lint/gemspec cleanups
+$ sj subfeature dependentnewthing
+Created feature branch dependentnewthing based on mynewthing
 ```
 
-while `binfo` on test2.1 looks like:
+If you create branches like this then sugarjar can now make several things
+much easier:
 
-```shell
-$ sj binfo
-* 36d0136 (HEAD -> test2.1) test2.1
-* e545b41 (test2) test2
-* c808eae (test1) test1
-o 44cf9e2 (origin/master, origin/HEAD, master) Lint/gemspec cleanups
+* `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"
+
+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.
+
+To continue with the example above, my `smartlist` 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)
+```
+
+This is simple. Now lets make a different feature stack:
+
+```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
+```
+
+The `smartlist` will now show us this tree, and it's a bit more interesting:
+
+```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)
+```
+
+Now, what happens if I make a change to `mynewthing`?
+
+```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)
+```
+
+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:
+
+```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)
+```
+
+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
+```
+
+### Creating Stacked PRs with subfeatures
+
+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`
+in your config to tell it to always do this (or `false` to never do this):
+
+```text
+$ sj spr
+Autofilling in PR from commit message
+It looks like this is a subfeature, would you like to base this PR on mynewthing? [y/n] y
+...
 ```
 
 ## Have a better lint/unittest experience!
@@ -259,41 +348,6 @@ merge.
 
 See `sj help` for more commands!
 
-## Using SugarJar as a git wrapper
-
-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.
-
-As such you can alias it to `git` and just have a super-git.
-
-```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
-```
-
-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.
-
-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!
-
 ## Configuration
 
 Sugarjar will read in both a system-level config file
@@ -312,6 +366,15 @@ 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.
 
+Deprecated fields will cause a warning, but you can suppress that warning by
+defining `ignore_deprecated_options`, for example:
+
+```yaml
+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
@@ -363,33 +426,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
 
@@ -401,15 +458,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
@@ -426,3 +474,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

data/bin/sj

@@ -13,7 +13,8 @@ SugarJar::Log.level = Logger::INFO
 
 # Don't put defaults here, put them in SugarJar::Config - otherwise
 # these defaults overwrite whatever is in config files.
-options = { 'color' => true }
+options = {}
+
 # If ENV['SUGARJAR_DEBUG'] is set, it overrides the config file,
 # but not the command line options, so set that one here. Also
 # start the logger at that level, in case we are debugging option loading
@@ -21,6 +22,7 @@ options = { 'color' => true }
 if ENV['SUGARJAR_LOGLEVEL']
   options['log_level'] = SugarJar::Log.level = ENV['SUGARJAR_LOGLEVEL'].to_sym
 end
+
 parser = OptionParser.new do |opts|
   opts.banner = 'Usage: sj <command> [<args>] [<options>]'
 
@@ -29,24 +31,10 @@ parser = OptionParser.new do |opts|
   opts.separator ''
   opts.separator 'OPTIONS:'
 
-  opts.on('--[no-]fallthru', 'Fall-thru to git. [default: true]') do |fallthru|
-    options['fallthru'] = fallthru
-  end
-
   opts.on('--feature-prefix', 'Prefix to use for feature branches') do |prefix|
     options['feature_prefix'] = prefix
   end
 
-  opts.on(
-    '--github-cli CLI',
-    %w{gh cli},
-    'Github CLI to use ("gh" or "hub" or "auto"). Auto (the default) will ' +
-    'prefer "gh" if it is available but will fall back to "hub." ' +
-    '[default: "auto"]',
-  ) do |cli|
-    options['github_cli'] = cli
-  end
-
   opts.on(
     '--github-host HOST',
     'The host for "hub". Note that we will set this in the local repo ' +
@@ -93,8 +81,8 @@ parser = OptionParser.new do |opts|
 
   opts.on(
     '--[no-]pr-autofill',
-    'When creating a PR, auto fill the title & description from the commit ' +
-    'if there is a single commit and if we are using "gh". [default: true]',
+    'When creating a PR, auto fill the title & description from the top ' +
+    'commit if we are using "gh". [default: true]',
   ) do |autofill|
     options['pr_autofill'] = autofill
   end
@@ -104,12 +92,12 @@ parser = OptionParser.new do |opts|
     'When creating a PR, if this is a subfeature, should we make it a ' +
     'PR on the PR for the parent feature. If not specified, we prompt ' +
     'when this happens, when true always do this, when false never do ' +
-    'this. Only applicable when usiing "gh".',
+    'this. Only applicable when usiing "gh" and on branch-based PRs.',
   ) do |autostack|
     options['pr_autostack'] = autostack
   end
 
-  opts.on('--[no-]use-color', 'Enable color. [default: true]') do |color|
+  opts.on('--[no-]color', 'Enable color. [default: true]') do |color|
     options['color'] = color
   end
 
@@ -119,7 +107,7 @@ parser = OptionParser.new do |opts|
   end
 
   # rubocop:disable Layout/HeredocIndentation
-  opts.separator <<COMMANDS
+  opts.separator <<COMMANDTEXT
 
 COMMANDS:
   amend
@@ -145,6 +133,10 @@ COMMANDS:
   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
@@ -209,99 +201,66 @@ COMMANDS:
 
   upall
               Same as "up", but for all branches.
-
-  version
-              Print the version of sugarjar, and then run 'hub version'
-              to show the hub and git versions.
-
-Be sure to checkout Sapling (https://sapling-scm.com/)! SugarJar was written as
-a stop-gap to get Sapling features before it was open-sourced, and as such
-Sapling may serve your needs even better.
-COMMANDS
+COMMANDTEXT
 
   # rubocop:enable Layout/HeredocIndentation
 end
 
-# we make a copy of these because we will assign back to the ARGV
-# we parse later. We also need a pristine copy in case we want to
-# run git as we were called.
-argv_copy = ARGV.dup
-
-# We don't have options yet, but we need an instance of SJ in order
-# to list public methods. We will recreate it
-sj = SugarJar::Commands.new(options.merge({ 'no_change' => true }))
 extra_opts = []
+argv_copy = ARGV.dup
 
-# as with above, this can't go into 'options', until after we parse
-# the command line args
-config = SugarJar::Config.config
-
-valid_commands = sj.public_methods - Object.public_methods
-possible_valid_command = ARGV.any? do |arg|
-  valid_commands.include?(arg.to_s.to_sym)
-end
-
-# if we're configured to fall thru and the subcommand isn't one
-# we recognize, don't parse the options as they may be different
-# than git's. For example `git config -l` - we error because we
-# require an arguement to `-l`.
-if config['fallthru'] && !possible_valid_command
-  SugarJar::Log.debug(
-    'Skipping option parsing: fall-thru is set and we do not recognize ' +
-    'any subcommands',
-  )
-else
+# We want to allow people to pass in extra args to be passed to commands (like
+# `amend`), but OptionParser doesn't easily allow this. So we loop over it,
+# catching exceptions.
+
+begin
+  # HOWEVER, anytime it throws an exception, for some reason, it clears
+  # out all of ARGV, or whatever you passed to as ARGV.
+  #
+  # This not only prevents further parsing, but also means we lose
+  # any non-option arguements (like the subcommand!)
+  #
+  # So we save a copy, and if we throw an exception, save the option that
+  # caused it, remove that option from our copy, and then re-populate argv
+  # with what's left.
+  #
+  # By doing this we not only get to parse all the options properly and
+  # save unknown ones, but non-option arguements, which OptionParser
+  # normally leaves in ARGV stay in ARGV.
+  saved_argv = argv_copy.dup
+  parser.parse!(argv_copy)
+rescue OptionParser::InvalidOption => e
+  SugarJar::Log.debug("Saving unknown argument #{e.args}")
+  extra_opts += e.args
+
+  # e.args is an array, but it's only ever one arguement per exception
+  saved_argv.delete(e.args.first)
+  argv_copy = saved_argv.dup
   SugarJar::Log.debug(
-    'We MIGHT have a valid command... parse-command line options',
+    "Continuing option parsing with remaining ARGV: #{argv_copy}",
   )
-  # We want to allow people to pass in extra args to be passed to
-  # git commands, but OptionParser doesn't easily allow this. So we
-  # loop over it, catching exceptions.
-  begin
-    # HOWEVER, anytime it throws an exception, for some reason, it clears
-    # out all of ARGV, or whatever you passed to as ARGV.
-    #
-    # This not only prevents further parsing, but also means we lose
-    # any non-option arguements (like the subcommand!)
-    #
-    # So we save a copy, and if we throw an exception, save the option that
-    # caused it, remove that option from our copy, and then re-populate argv
-    # with what's left.
-    #
-    # By doing this we not only get to parse all the options properly and
-    # save unknown ones, but non-option arguements, which OptionParser
-    # normally leaves in ARGV stay in ARGV.
-    saved_argv = argv_copy.dup
-    parser.parse!(argv_copy)
-  rescue OptionParser::InvalidOption => e
-    SugarJar::Log.debug("Saving unknown argument #{e.args}")
-    extra_opts += e.args
-
-    # e.args is an array, but it's only ever one arguement per exception
-    saved_argv.delete(e.args.first)
-    argv_copy = saved_argv.dup
-    SugarJar::Log.debug(
-      "Continuing option parsing with remaining ARGV: #{argv_copy}",
-    )
-    retry
-  end
+  retry
 end
 
-subcommand = argv_copy.reject { |x| x.start_with?('-') }.first
+options = SugarJar::Config.config.merge(options)
+SugarJar::Log.level = options['log_level'].to_sym if options['log_level']
 
+subcommand = argv_copy.reject { |x| x.start_with?('-') }.first
 if ARGV.empty? || !subcommand
   puts parser
   exit
 end
 
-options = config.merge(options)
+SugarJar::Log.debug("Final config: #{options}")
 
-# Recreate SJ with all of our options
-SugarJar::Log.level = options['log_level'].to_sym if options['log_level']
 sj = SugarJar::Commands.new(options)
-
+valid_commands = sj.public_methods - Object.public_methods
 is_valid_command = valid_commands.include?(subcommand.to_sym)
-argv_copy.delete(subcommand)
+# We can't do .delete(subcommand) because someone could, for example
+# have a branch called 'co' and then do 'sj co co' - which will then
+# remove _all_ instances of 'co'. So find the first instance and remove
+# that.
+argv_copy.delete_at(argv_copy.find_index(subcommand))
 SugarJar::Log.debug("subcommand is #{subcommand}")
 
 # Extra options we got, plus any left over arguements are what we
@@ -309,25 +268,20 @@ SugarJar::Log.debug("subcommand is #{subcommand}")
 extra_opts += argv_copy
 SugarJar::Log.debug("extra unknown options: #{extra_opts}")
 
-if subcommand == 'help'
+case subcommand
+when 'help'
   puts parser
   exit
+when 'debuginfo'
+  extra_opts = [options]
 end
 
-if is_valid_command
-  SugarJar::Log.debug(
-    "running #{subcommand}; extra opts: #{extra_opts.join(', ')}",
-  )
-  sj.send(subcommand.to_sym, *extra_opts)
-elsif options['fallthru']
-  SugarJar::Log.debug("Falling thru to: hub #{ARGV.join(' ')}")
-  if options['github_cli'] == 'hub'
-    exec('hub', *ARGV)
-  else
-    # If we're using 'gh', it doesn't have 'git fall thru' support, so
-    # we pass thru directly to 'git'
-    exec('git', *ARGV)
-  end
-else
-  SugarJar::Log.error("No such subcommand: #{subcommand}")
+unless is_valid_command
+  SugarJar::Log.fatal("No such subcommand: #{subcommand}")
+  exit 1
 end
+
+SugarJar::Log.debug(
+  "running #{subcommand}; extra opts: #{extra_opts.join(', ')}",
+)
+sj.send(subcommand.to_sym, *extra_opts)