Re: [PATCH v4 9/9] checkout & worktree: introduce checkout.defaultRemote

[Thomas Gummerer <t.gummerer@gmail.com>]

On 05/31, Ævar Arnfjörð Bjarmason wrote:
> Introduce a checkout.defaultRemote setting which can be used to
> designate a remote to prefer (via checkout.defaultRemote=origin) when
> running e.g. "git checkout master" to mean origin/master, even though
> there's other remotes that have the "master" branch.
> 
> I want this because it's very handy to use this workflow to checkout a
> repository and create a topic branch, then get back to a "master" as
> retrieved from upstream:
> 
>     (
>         cd /tmp &&
>         rm -rf tbdiff &&
>         git clone git@github.com:trast/tbdiff.git &&
>         cd tbdiff &&
>         git branch -m topic &&
>         git checkout master
>     )
> 
> That will output:
> 
>     Branch 'master' set up to track remote branch 'master' from 'origin'.
>     Switched to a new branch 'master'
> 
> But as soon as a new remote is added (e.g. just to inspect something
> from someone else) the DWIMery goes away:
> 
>     (
>         cd /tmp &&
>         rm -rf tbdiff &&
>         git clone git@github.com:trast/tbdiff.git &&
>         cd tbdiff &&
>         git branch -m topic &&
>         git remote add avar git@github.com:avar/tbdiff.git &&
>         git fetch avar &&
>         git checkout master
>     )
> 
> Will output (without the advice output added earlier in this series):
> 
>     error: pathspec 'master' did not match any file(s) known to git.
> 
> The new checkout.defaultRemote config allows me to say that whenever
> that ambiguity comes up I'd like to prefer "origin", and it'll still
> work as though the only remote I had was "origin".
> 
> Also adjust the advice.checkoutAmbiguousRemoteBranchName message to
> mention this new config setting to the user, the full output on my
> git.git is now (the last paragraph is new):
> 
>     $ ./git --exec-path=$PWD checkout master
>     error: pathspec 'master' did not match any file(s) known to git.
>     hint: The argument 'master' matched more than one remote tracking branch.
>     hint: We found 26 remotes with a reference that matched. So we fell back
>     hint: on trying to resolve the argument as a path, but failed there too!
>     hint:
>     hint: Perhaps you meant fully qualify the branch name? E.g. origin/<name>
>     hint: instead of <name>?
>     hint:
>     hint: If you'd like to always have checkouts of 'master' prefer one remote,
>     hint: e.g. the 'origin' remote, consider setting checkout.defaultRemote=origin
>     hint: in your config. See the 'git-config' manual page for details.
> 
> I considered splitting this into checkout.defaultRemote and
> worktree.defaultRemote, but it's probably less confusing to break our
> own rules that anything shared between config should live in core.*
> than have two config settings, and I couldn't come up with a short
> name under core.* that made sense (core.defaultRemoteForCheckout?).

I agree that splitting this into two variables would be needlessly
confusing.  'checkout' and 'worktree add' are similar enough in
spirit, that users only setting one of the configuration variables
would end up confused at some point.  Because the commands are so
similar, I also feel like it would be okay to break our own rules
here, and use the 'core.defaultRemote' name you suggested (I also
can't come up with anything better in core.* right now).

> See also 70c9ac2f19 ("DWIM "git checkout frotz" to "git checkout -b
> frotz origin/frotz"", 2009-10-18) which introduced this DWIM feature
> to begin with, and 4e85333197 ("worktree: make add <path> <branch>
> dwim", 2017-11-26) which added it to git-worktree.
> 
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
>  Documentation/config.txt       | 21 ++++++++++++++++++++-
>  Documentation/git-checkout.txt |  9 +++++++++
>  Documentation/git-worktree.txt |  9 +++++++++
>  builtin/checkout.c             | 15 +++++++++++----
>  checkout.c                     | 21 ++++++++++++++++++++-
>  checkout.h                     |  5 ++++-
>  t/t2024-checkout-dwim.sh       | 12 ++++++++++++
>  t/t2025-worktree-add.sh        | 21 +++++++++++++++++++++
>  8 files changed, 106 insertions(+), 7 deletions(-)
>
> [snip]
>
> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> index ca5fc9c798..8cb77bddeb 100644
> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -38,6 +38,15 @@ equivalent to
>  $ git checkout -b <branch> --track <remote>/<branch>
>  ------------
>  +
> +If the branch exists in multiple remotes and one of them is named by
> +the `checkout.defaultRemote` configuration variable, we'll use that
> +one for the purposes of disambiguation, even if the `<branch>` isn't
> +unique across all remotes. Set it to
> +e.g. `checkout.defaultRemote=origin` to always checkout remote
> +branches from there if `<branch> is ambiguous but exists on the

s/`<branch>/&`/

> +'origin' remote. See also `checkout.defaultRemote` in
> +linkgit:git-config[1].
> ++
>  You could omit <branch>, in which case the command degenerates to
>  "check out the current branch", which is a glorified no-op with
>  rather expensive side-effects to show only the tracking information,
> diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
> index afc6576a14..6638d5ca3d 100644
> --- a/Documentation/git-worktree.txt
> +++ b/Documentation/git-worktree.txt
> @@ -60,6 +60,15 @@ with a matching name, treat as equivalent to:
>  $ git worktree add --track -b <branch> <path> <remote>/<branch>
>  ------------
>  +
> +If the branch exists in multiple remotes and one of them is named by
> +the `checkout.defaultRemote` configuration variable, we'll use that
> +one for the purposes of disambiguation, even if the `<branch>` isn't
> +unique across all remotes. Set it to
> +e.g. `checkout.defaultRemote=origin` to always checkout remote
> +branches from there if `<branch> is ambiguous but exists on the

s/`<branch>/&`/

> +'origin' remote. See also `checkout.defaultRemote` in
> +linkgit:git-config[1].
> ++
>  If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used,
>  then, as a convenience, the new worktree is associated with a branch
>  (call it `<branch>`) named after `$(basename <path>)`.  If `<branch>`
>
> [snip]
>
> -- 
> 2.17.0.290.gded63e768a
>