[PATCH] git-jump: pick a mode automatically when invoked without arguments

[PATCH] git-jump: pick a mode automatically when invoked without arguments

[Greg Hurrell via GitGitGadget]

From: Greg Hurrell <greg.hurrell@datadoghq.com>

When `git jump` is invoked with no positional arguments (and no
arguments after `--stdout`) it currently prints usage and exits with
status 1.

But there are two situations where we can usefully infer the most
valuable and likely mode that a user would want to use, and select it
automatically when they run `git jump` without arguments:

1. When there are unmerged paths in the index, the user likely
   wants `git jump merge`.

2. When the working tree has unstaged changes, the user likely
   wants `git jump diff`.

Detect these two cases and dispatch to the corresponding mode
automatically, falling back to the existing usage-and-exit behavior
when neither holds.

Signed-off-by: Greg Hurrell <greg.hurrell@datadoghq.com>
---
    git-jump: pick a mode automatically when invoked without arguments

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2108%2Fwincent%2Fauto-jump-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2108/wincent/auto-jump-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/2108

 contrib/git-jump/README   |  4 ++++
 contrib/git-jump/git-jump | 16 +++++++++++++---
 2 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/contrib/git-jump/README b/contrib/git-jump/README
index 3211841305..420b20b6a2 100644
--- a/contrib/git-jump/README
+++ b/contrib/git-jump/README
@@ -55,6 +55,10 @@ To use it, just drop git-jump in your PATH, and then invoke it like
 this:
 
 --------------------------------------------------
+# pick a mode automatically: "merge" if there are unmerged paths,
+# "diff" if the worktree has unstaged changes, otherwise show usage
+git jump
+
 # jump to changes not yet staged for commit
 git jump diff
 
diff --git a/contrib/git-jump/git-jump b/contrib/git-jump/git-jump
index 8d1d5d79a6..ac0ad2f037 100755
--- a/contrib/git-jump/git-jump
+++ b/contrib/git-jump/git-jump
@@ -2,7 +2,7 @@
 
 usage() {
 	cat <<\EOF
-usage: git jump [--stdout] <mode> [<args>]
+usage: git jump [--stdout] [<mode>] [<args>]
 
 Jump to interesting elements in an editor.
 The <mode> parameter is one of:
@@ -99,8 +99,18 @@ while test $# -gt 0; do
 	shift
 done
 if test $# -lt 1; then
-	usage >&2
-	exit 1
+	if test "$(git rev-parse --is-inside-work-tree 2>/dev/null)" != "true"; then
+		usage >&2
+		exit 1
+	fi
+	if test -n "$(git ls-files -u)"; then
+		set -- merge
+	elif ! git diff --quiet; then
+		set -- diff
+	else
+		usage >&2
+		exit 1
+	fi
 fi
 mode=$1; shift
 type "mode_$mode" >/dev/null 2>&1 || { usage >&2; exit 1; }

base-commit: 94f057755b7941b321fd11fec1b2e3ca5313a4e0
-- 
gitgitgadget

Re: [PATCH] git-jump: pick a mode automatically when invoked without arguments

[Jeff King]

On Fri, May 08, 2026 at 09:07:34AM +0000, Greg Hurrell via GitGitGadget wrote:

> From: Greg Hurrell <greg.hurrell@datadoghq.com>
> 
> When `git jump` is invoked with no positional arguments (and no
> arguments after `--stdout`) it currently prints usage and exits with
> status 1.
> 
> But there are two situations where we can usefully infer the most
> valuable and likely mode that a user would want to use, and select it
> automatically when they run `git jump` without arguments:
> 
> 1. When there are unmerged paths in the index, the user likely
>    wants `git jump merge`.
> 
> 2. When the working tree has unstaged changes, the user likely
>    wants `git jump diff`.
> 
> Detect these two cases and dispatch to the corresponding mode
> automatically, falling back to the existing usage-and-exit behavior
> when neither holds.

OK, I guess this saves a little bit of typing. I never really thought
about it because I long ago aliased the various invocations in my shell
("git jump diff" in particular is so useful that it is just "d" in my
shell).

I'd be a little worried that it is more confusing to somebody
approaching the command for the first time and just runs "git jump" to
not see usage or other guidance. But that might be overly paranoid.

Would having "git jump auto" work for you? I.e., are you primarily
trying to avoid the mental effort of selecting the command, or the
finger effort of typing it?

>  if test $# -lt 1; then
> -	usage >&2
> -	exit 1
> +	if test "$(git rev-parse --is-inside-work-tree 2>/dev/null)" != "true"; then
> +		usage >&2
> +		exit 1
> +	fi
> +	if test -n "$(git ls-files -u)"; then
> +		set -- merge
> +	elif ! git diff --quiet; then
> +		set -- diff
> +	else
> +		usage >&2
> +		exit 1
> +	fi

The implementation looks reasonable. In theory we could save a diff
invocation by trying diff mode and reporting whether it found anything.
But the --quiet invocation is not too expensive, and avoiding it is
probably not worth the gymnastics required.

-Peff

Re: [PATCH] git-jump: pick a mode automatically when invoked without arguments

[Greg Hurrell]

On Fri, May 8, 2026, at 4:13 PM, Jeff King wrote:
> On Fri, May 08, 2026 at 09:07:34AM +0000, Greg Hurrell via GitGitGadget wrote:
> 
> I'd be a little worried that it is more confusing to somebody
> approaching the command for the first time and just runs "git jump" to
> not see usage or other guidance. But that might be overly paranoid.

Hopefully, they at least read the README before installing it from contrib/
(although Homebrew recently starting installing it for folks automatically,
so may not remain true for much longer on macOS...)
 
> Would having "git jump auto" work for you? I.e., are you primarily
> trying to avoid the mental effort of selecting the command, or the
> finger effort of typing it?

It's mostly the finger effort of typing it because I generally know exactly
which mode I want; eg.

- I'm in the middle of a rebase, and hit a conflict; 100% of the time,
  I want to explore the conflicts, so I want `git jump` to do `git jump
  merge`.

- I have unstaged changes, and I want to make some tweaks before committing;
  so I want `git jump` to do `git jump diff`.

- Otherwise, I'm wanting to search for something (ie. `git jump grep`),
  so by definition I'm going to be doing some extra typing anyway (ie.
  `git jump grep <pattern>`).

This is muscle memory for me at this point, because I've had a `git jump`
alias for this in my dotfiles[^1] for a couple of years. Homebrew
installing `git-jump` by default a few months ago[^2] broke this, because
aliases can't shadow builtin commands.

[^1]: https://github.com/wincent/wincent/commit/99183f86fe35
[^2]: https://github.com/Homebrew/homebrew-core/commit/e9fc066240f2

Best wishes,
Greg

Re: [PATCH] git-jump: pick a mode automatically when invoked without arguments

[Jeff King]

On Fri, May 08, 2026 at 04:30:36PM +0200, Greg Hurrell wrote:

> On Fri, May 8, 2026, at 4:13 PM, Jeff King wrote:
> > On Fri, May 08, 2026 at 09:07:34AM +0000, Greg Hurrell via GitGitGadget wrote:
> > 
> > I'd be a little worried that it is more confusing to somebody
> > approaching the command for the first time and just runs "git jump" to
> > not see usage or other guidance. But that might be overly paranoid.
> 
> Hopefully, they at least read the README before installing it from contrib/
> (although Homebrew recently starting installing it for folks automatically,
> so may not remain true for much longer on macOS...)

Yeah, I'd hope so. And even if it might be more discoverable, I'm not
sure that is more important than being convenient for experienced users.

I guess a config option would be possible, but probably not worth it for
something as trivial as git-jump.

> It's mostly the finger effort of typing it because I generally know exactly
> which mode I want; eg.

OK, that makes sense.

> This is muscle memory for me at this point, because I've had a `git jump`
> alias for this in my dotfiles[^1] for a couple of years. Homebrew
> installing `git-jump` by default a few months ago[^2] broke this, because
> aliases can't shadow builtin commands.

Ah, yeah, that is frustrating. We try to avoid aliases overrides to
prevent confusion, but for an add-on tool like git-jump I think it is
overly cautious. It might be reasonable to limit that protection only to
commands in Git's exec-path, but I haven't thought hard about it. And I
think it should be considered separately from this patch anyway.

So yeah, your patch looks good to me. Thanks.

-Peff

Re: [PATCH] git-jump: pick a mode automatically when invoked without arguments

[Erik Cervin Edin]

On 26/05/08 04:30PM, Greg Hurrell wrote:
> Hopefully, they at least read the README before installing it from contrib/
> (although Homebrew recently starting installing it for folks automatically,
> so may not remain true for much longer on macOS...)

Oh! I didn't know that but looking closer on my homebrew installed Git,
looks like you're right.

I would've assumed that if users had jumped through the hoops of
installing git-jump from contrib/ it stands to reason they would have
some sense of what it does. But if this is landing as a part of regular
brew install git, I'd wager there's a few unsuspecting people running
git-jump that don't know what it does.

> Would having "git jump auto" work for you?

Imo, this sounds ideal -- there's something odd about `git jump` picking
the subcommand heuristically. At least when I invoke git-jump I always
do so with a specific intent of _where_ I want to jump. Then again, I
never do a jump merge or a jump ws.

> Homebrew installing `git-jump` by default a few months ago[^2] broke
> this, because aliases can't shadow builtin commands.

But it looks like this doesn't work in this case. Even if you have
git-jump installed stand-alone (mine is in ~/bin/git-jump, in PATH,
before /opt/homebrew/bin.)

FWIW I alias jump to j, jump diff to jd and jump grep to jg. E.g.

    git jd # git jump diff

On 26/05/08 09:07AM, Greg Hurrell via GitGitGadget wrote:
> -usage: git jump [--stdout] <mode> [<args>]
> +usage: git jump [--stdout] [<mode>] [<args>]

The usage message makes <mode> optional but doesn't explain what
happens when you omit it. Seems worth documenting the auto-detect behavior
there too.

> But there are two situations where we can usefully infer the most
> valuable and likely mode that a user would want to use, and select it
> automatically when they run `git jump` without arguments:
>
> 1. When there are unmerged paths in the index, the user likely
>    wants `git jump merge`.
>
> 2. When the working tree has unstaged changes, the user likely
>    wants `git jump diff`.

I can think of a third situation -- when there are staged changes flagged by
git diff --cached --check.

If we're going to teach git-jump how to be more clever about where to jump,
does it also make sense to bake `git jump ws` into this?

Also, if this is going to grow into a proper auto-detect heuristic, it
might be cleaner as a first-class mode rather than logic spliced into the
argument parser. Something like:

    mode_auto() {
        if test -n "$(git ls-files -u)"; then
            mode_merge "$@"
        elif ! git diff --quiet; then
            mode_diff "$@"
        elif ! git diff --cached --check >/dev/null 2>&1; then
            mode_ws --cached "$@"
        else
            return 0
        fi
    }

That way `git jump auto` works explicitly, bare `git jump` defaults
to it (just `set -- auto` when $# -lt 1), and the usage text can
document the heuristic. It also keeps the detection and dispatch in
one place in case someone wants to tweak the priority later.

All in all, I think an auto jumping mode could be genuinely useful.

Re: [PATCH] git-jump: pick a mode automatically when invoked without arguments

[Greg Hurrell]

On Thu, May 14, 2026, at 5:40 PM, Erik Cervin Edin wrote:
> On 26/05/08 09:07AM, Greg Hurrell via GitGitGadget wrote:
> > -usage: git jump [--stdout] <mode> [<args>]
> > +usage: git jump [--stdout] [<mode>] [<args>]
> 
> The usage message makes <mode> optional but doesn't explain what
> happens when you omit it. Seems worth documenting the auto-detect behavior
> there too.
> 
> If we're going to teach git-jump how to be more clever about where to jump,
> does it also make sense to bake `git jump ws` into this?
> 
> Also, if this is going to grow into a proper auto-detect heuristic, it
> might be cleaner as a first-class mode rather than logic spliced into the
> argument parser. Something like:
> 
>     mode_auto() {
>         if test -n "$(git ls-files -u)"; then
>             mode_merge "$@"
>         elif ! git diff --quiet; then
>             mode_diff "$@"
>         elif ! git diff --cached --check >/dev/null 2>&1; then
>             mode_ws --cached "$@"
>         else
>             return 0
>         fi
>     }
> 
> That way `git jump auto` works explicitly, bare `git jump` defaults
> to it (just `set -- auto` when $# -lt 1), and the usage text can
> document the heuristic. It also keeps the detection and dispatch in
> one place in case someone wants to tweak the priority later.

All of those suggestions sound reasonable to me. Jeff, do you agree?
If so, I can update the patch.

Best wishes,
Greg

Re: [PATCH] git-jump: pick a mode automatically when invoked without arguments

[Jeff King]

On Tue, May 19, 2026 at 11:03:44AM +0200, Greg Hurrell wrote:

> On Thu, May 14, 2026, at 5:40 PM, Erik Cervin Edin wrote:
> > On 26/05/08 09:07AM, Greg Hurrell via GitGitGadget wrote:
> > > -usage: git jump [--stdout] <mode> [<args>]
> > > +usage: git jump [--stdout] [<mode>] [<args>]
> > 
> > The usage message makes <mode> optional but doesn't explain what
> > happens when you omit it. Seems worth documenting the auto-detect behavior
> > there too.
> > 
> > If we're going to teach git-jump how to be more clever about where to jump,
> > does it also make sense to bake `git jump ws` into this?
> > 
> > Also, if this is going to grow into a proper auto-detect heuristic, it
> > might be cleaner as a first-class mode rather than logic spliced into the
> > argument parser. Something like:
> > 
> >     mode_auto() {
> >         if test -n "$(git ls-files -u)"; then
> >             mode_merge "$@"
> >         elif ! git diff --quiet; then
> >             mode_diff "$@"
> >         elif ! git diff --cached --check >/dev/null 2>&1; then
> >             mode_ws --cached "$@"
> >         else
> >             return 0
> >         fi
> >     }
> > 
> > That way `git jump auto` works explicitly, bare `git jump` defaults
> > to it (just `set -- auto` when $# -lt 1), and the usage text can
> > document the heuristic. It also keeps the detection and dispatch in
> > one place in case someone wants to tweak the priority later.
> 
> All of those suggestions sound reasonable to me. Jeff, do you agree?
> If so, I can update the patch.

Yeah, I agree that having an explicit "auto" mode (and then just
defaulting to it) makes perfect sense.

I don't really have an opinion on adding "ws" in here. Despite being the
person who added the whitespace mode in the first place, I can't
remember ever using it in the last 10 years. ;) But the cost is fairly
low to support it, so we might as well.

-Peff

[PATCH v2] git-jump: pick a mode automatically when invoked without arguments

[Greg Hurrell via GitGitGadget]

From: Greg Hurrell <greg.hurrell@datadoghq.com>

When `git jump` is invoked with no positional arguments (and no
arguments after `--stdout`) it currently prints usage and exits with
status 1.

But there are several situations where we can usefully infer the most
valuable and likely mode that a user would want to use, and select it
automatically:

1. When there are unmerged paths in the index, the user likely
   wants `git jump merge`.

2. When the working tree has unstaged changes, the user likely
   wants `git jump diff`.

3. In the presence of conflict markers or whitespace errors (as reported
   by `git diff --check`), the user likely wants `git jump ws`.

In this commit we teach `git jump` a new "auto" mode which detects these
cases and dispatches to the corresponding mode automatically. The user
can either explicitly spell out `git jump auto`, or just leave it at
`git jump` (because "auto" is the default).

If none of the interesting cases listed above applies, then auto mode
falls back to the existing usage-and-exit behavior.

Signed-off-by: Greg Hurrell <greg.hurrell@datadoghq.com>
---
    git-jump: pick a mode automatically when invoked without arguments
    
    Changes since v0:
    
     * Added explicit "auto" keyword/mode.
     * Updated additional detail to usage info and README.
     * (Bonus) Added ws usage example to README.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2108%2Fwincent%2Fauto-jump-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2108/wincent/auto-jump-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/2108

Range-diff vs v1:

 1:  87fa66d233 ! 1:  5fbc8480ef git-jump: pick a mode automatically when invoked without arguments
     @@ Commit message
          arguments after `--stdout`) it currently prints usage and exits with
          status 1.
      
     -    But there are two situations where we can usefully infer the most
     +    But there are several situations where we can usefully infer the most
          valuable and likely mode that a user would want to use, and select it
     -    automatically when they run `git jump` without arguments:
     +    automatically:
      
          1. When there are unmerged paths in the index, the user likely
             wants `git jump merge`.
     @@ Commit message
          2. When the working tree has unstaged changes, the user likely
             wants `git jump diff`.
      
     -    Detect these two cases and dispatch to the corresponding mode
     -    automatically, falling back to the existing usage-and-exit behavior
     -    when neither holds.
     +    3. In the presence of conflict markers or whitespace errors (as reported
     +       by `git diff --check`), the user likely wants `git jump ws`.
     +
     +    In this commit we teach `git jump` a new "auto" mode which detects these
     +    cases and dispatches to the corresponding mode automatically. The user
     +    can either explicitly spell out `git jump auto`, or just leave it at
     +    `git jump` (because "auto" is the default).
     +
     +    If none of the interesting cases listed above applies, then auto mode
     +    falls back to the existing usage-and-exit behavior.
      
          Signed-off-by: Greg Hurrell <greg.hurrell@datadoghq.com>
      
       ## contrib/git-jump/README ##
     -@@ contrib/git-jump/README: To use it, just drop git-jump in your PATH, and then invoke it like
     - this:
     +@@ contrib/git-jump/README: git jump grep foo_bar
     + # arbitrary grep options
     + git jump grep -i foo_bar
       
     - --------------------------------------------------
     ++# jump to places with conflict markers or whitespace errors
     ++# (as reported by # `git diff --check`)
     ++git jump ws
     ++
     + # use the silver searcher for git jump grep
     + git config jump.grepCmd "ag --column"
     ++
      +# pick a mode automatically: "merge" if there are unmerged paths,
     -+# "diff" if the worktree has unstaged changes, otherwise show usage
     -+git jump
     ++# "diff" if the worktree has unstaged changes, "ws" if there are
     ++# whitespace problems; otherwise show usage
     ++git jump auto
      +
     - # jump to changes not yet staged for commit
     - git jump diff
     ++# with no explicit mode, same as "auto"
     ++git jump
     + --------------------------------------------------
       
     + You can use the optional argument '--stdout' to print the listing to
      
       ## contrib/git-jump/git-jump ##
      @@
     @@ contrib/git-jump/git-jump
      +usage: git jump [--stdout] [<mode>] [<args>]
       
       Jump to interesting elements in an editor.
     - The <mode> parameter is one of:
     -@@ contrib/git-jump/git-jump: while test $# -gt 0; do
     - 	shift
     - done
     - if test $# -lt 1; then
     --	usage >&2
     --	exit 1
     +-The <mode> parameter is one of:
     ++The <mode> parameter is one of the following,
     ++defaulting to "auto" if omitted:
     + 
     + diff: elements are diff hunks. Arguments are given to diff.
     + 
     +@@ contrib/git-jump/git-jump: grep: elements are grep hits. Arguments are given to git grep or, if
     + 
     + ws: elements are whitespace errors. Arguments are given to diff --check.
     + 
     ++auto: select one of the other modes based on worktree state;
     ++      "merge" if there are unmerged paths, "diff" if there are
     ++      unstaged changes, "ws" if there are whitespace errors.
     ++
     + If the optional argument `--stdout` is given, print the quickfix
     + lines to standard output instead of feeding it to the editor.
     + EOF
     +@@ contrib/git-jump/git-jump: mode_ws() {
     + 	git diff --check "$@"
     + }
     + 
     ++mode_auto() {
      +	if test "$(git rev-parse --is-inside-work-tree 2>/dev/null)" != "true"; then
      +		usage >&2
      +		exit 1
      +	fi
     -+	if test -n "$(git ls-files -u)"; then
     -+		set -- merge
     -+	elif ! git diff --quiet; then
     -+		set -- diff
     ++	if test -n "$(git ls-files -u "$@")"; then
     ++		mode_merge "$@"
     ++	elif ! git diff --quiet "$@"; then
     ++		mode_diff "$@"
     ++	elif ! git diff --check >/dev/null 2>&1; then
     ++		mode_ws "$@"
      +	else
      +		usage >&2
      +		exit 1
      +	fi
     ++}
     ++
     + use_stdout=
     + while test $# -gt 0; do
     + 	case "$1" in
     +@@ contrib/git-jump/git-jump: while test $# -gt 0; do
     + 	shift
     + done
     + if test $# -lt 1; then
     +-	usage >&2
     +-	exit 1
     ++	set -- auto
       fi
       mode=$1; shift
       type "mode_$mode" >/dev/null 2>&1 || { usage >&2; exit 1; }


 contrib/git-jump/README   | 12 ++++++++++++
 contrib/git-jump/git-jump | 29 +++++++++++++++++++++++++----
 2 files changed, 37 insertions(+), 4 deletions(-)

diff --git a/contrib/git-jump/README b/contrib/git-jump/README
index 3211841305..ac35792e55 100644
--- a/contrib/git-jump/README
+++ b/contrib/git-jump/README
@@ -75,8 +75,20 @@ git jump grep foo_bar
 # arbitrary grep options
 git jump grep -i foo_bar
 
+# jump to places with conflict markers or whitespace errors
+# (as reported by # `git diff --check`)
+git jump ws
+
 # use the silver searcher for git jump grep
 git config jump.grepCmd "ag --column"
+
+# pick a mode automatically: "merge" if there are unmerged paths,
+# "diff" if the worktree has unstaged changes, "ws" if there are
+# whitespace problems; otherwise show usage
+git jump auto
+
+# with no explicit mode, same as "auto"
+git jump
 --------------------------------------------------
 
 You can use the optional argument '--stdout' to print the listing to
diff --git a/contrib/git-jump/git-jump b/contrib/git-jump/git-jump
index 8d1d5d79a6..43d3b42a41 100755
--- a/contrib/git-jump/git-jump
+++ b/contrib/git-jump/git-jump
@@ -2,10 +2,11 @@
 
 usage() {
 	cat <<\EOF
-usage: git jump [--stdout] <mode> [<args>]
+usage: git jump [--stdout] [<mode>] [<args>]
 
 Jump to interesting elements in an editor.
-The <mode> parameter is one of:
+The <mode> parameter is one of the following,
+defaulting to "auto" if omitted:
 
 diff: elements are diff hunks. Arguments are given to diff.
 
@@ -16,6 +17,10 @@ grep: elements are grep hits. Arguments are given to git grep or, if
 
 ws: elements are whitespace errors. Arguments are given to diff --check.
 
+auto: select one of the other modes based on worktree state;
+      "merge" if there are unmerged paths, "diff" if there are
+      unstaged changes, "ws" if there are whitespace errors.
+
 If the optional argument `--stdout` is given, print the quickfix
 lines to standard output instead of feeding it to the editor.
 EOF
@@ -82,6 +87,23 @@ mode_ws() {
 	git diff --check "$@"
 }
 
+mode_auto() {
+	if test "$(git rev-parse --is-inside-work-tree 2>/dev/null)" != "true"; then
+		usage >&2
+		exit 1
+	fi
+	if test -n "$(git ls-files -u "$@")"; then
+		mode_merge "$@"
+	elif ! git diff --quiet "$@"; then
+		mode_diff "$@"
+	elif ! git diff --check >/dev/null 2>&1; then
+		mode_ws "$@"
+	else
+		usage >&2
+		exit 1
+	fi
+}
+
 use_stdout=
 while test $# -gt 0; do
 	case "$1" in
@@ -99,8 +121,7 @@ while test $# -gt 0; do
 	shift
 done
 if test $# -lt 1; then
-	usage >&2
-	exit 1
+	set -- auto
 fi
 mode=$1; shift
 type "mode_$mode" >/dev/null 2>&1 || { usage >&2; exit 1; }

base-commit: 1c00d2d8392f603a6263f11f1a50fde96ae5475e
-- 
gitgitgadget