[PATCH v2 0/2] adding new branch.autosetupmerge option "simple"

Re-sending with proposed fixes to concerns raised by Junio.

This patchset introduces a new option to the branch.autosetupmerge setting, "simple", which is intended to be consistent with and complementary to the push.default "simple" option.

The push.defaut option "simple" helps produce predictable/understandable behavior for beginners, where they don't accidentally push to the "wrong" branch in centralized workflows. If they create a local branch with a different name and then try to do a plain push, it will helpfully fail and explain why.

However, such users can often find themselves confused by the behavior of git after they first branch, and before they push. At that stage, their upstream tracking branch is the original remote branch, and pull will be bringing in "upstream changes" - eg all changes to "main", in a typical project where that's where they branched from. On the other hand, once they push their new branch (dealing with the initial error, following instructions to push to the right name), subsequent "pull" calls will behave as expected, only bring in any changes to that new branch they pushed.

The new option introduced here, with push.default set to simple, ensures that push/pull behavior is generally consistent - tracking will be automatically set up for branches that push will work for (and pull will be consistent for) only.

Tao Klerks (2):
  merge: new autosetupmerge option 'simple' for matching branches
  t3200: tests for new branch.autosetupmerge option "simple"

 Documentation/config/branch.txt |  4 +++-
 Documentation/git-branch.txt    | 18 ++++++++++-------
 branch.c                        | 19 ++++++++++++++++++
 branch.h                        |  1 +
 config.c                        |  3 +++
 t/t3200-branch.sh               | 35 +++++++++++++++++++++++++++++++++
 6 files changed, 72 insertions(+), 8 deletions(-)

base-commit: dab1b7905d0b295f1acef9785bb2b9cbb0fdec84
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1161%2FTaoK%2Ffeature-branch-autosetupmerge-simple-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1161/TaoK/feature-branch-autosetupmerge-simple-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1161

Range-diff vs v1:

 1:  89efc1e1564 ! 1:  890e016bfc0 merge: new autosetupmerge option 'simple' for matching branches
     @@ Metadata
       ## Commit message ##
          merge: new autosetupmerge option 'simple' for matching branches
      
     -    The push.defaut option "simple" helps produce
     -    predictable/understandable behavior for beginners,
     -    where they don't accidentally push to the
     -    "wrong" branch in centralized workflows. If they
     -    create a local branch with a different name
     -    and then try to do a plain push, it will
     -    helpfully fail and explain why.
     +    This commit introduces a new option to the branch.autosetupmerge
     +    setting, "simple", which is intended to be consistent with and
     +    complementary to the push.default "simple" option.
      
     -    However, such users can often find themselves
     -    confused by the behavior of git after they first
     -    branch, and before they push. At that stage,
     -    their upstream tracking branch is the original
     -    remote branch, and pull (for example) behaves
     -    very differently to how it later does when they
     -    create their own same-name remote branch.
     +    The push.defaut option "simple" helps produce
     +    predictable/understandable behavior for beginners, where they don't
     +    accidentally push to the "wrong" branch in centralized workflows. If
     +    they create a local branch with a different name and then try to do a
     +    plain push, it will helpfully fail and explain why.
      
     -    This commit introduces a new option to the
     -    branch.autosetupmerge setting, "simple",
     -    which is intended to be consistent with and
     -    complementary to the push.default "simple"
     -    option.
     +    However, such users can often find themselves confused by the behavior
     +    of git after they first branch, and before they push. At that stage,
     +    their upstream tracking branch is the original remote branch, and pull
     +    will be bringing in "upstream changes" - eg all changes to "main", in
     +    a typical project where that's where they branched from.
     +    On the other hand, once they push their new branch (dealing with the
     +    initial error, following instructions to push to the right name),
     +    subsequent "pull" calls will behave as expected, only bring in any
     +    changes to that new branch they pushed.
      
     -    It will set up automatic tracking for a new
     -    branch only if the remote ref is a branch and
     -    that remote branch name matches the new local
     -    branch name. It is a reduction in scope of
     -    the existing default option, "true".
     +    The new option introduced here, with push.default set to simple,
     +    ensures that push/pull behavior is generally consistent - tracking
     +    will be automatically set up for branches that push will work for
     +    (and pull will be consistent for) only.
      
          Signed-off-by: Tao Klerks <tao@klerks.biz>
      
     + ## Documentation/config/branch.txt ##
     +@@ Documentation/config/branch.txt: branch.autoSetupMerge::
     + 	automatic setup is done when the starting point is either a
     + 	local branch or remote-tracking branch; `inherit` -- if the starting point
     + 	has a tracking configuration, it is copied to the new
     +-	branch. This option defaults to true.
     ++	branch; `simple` -- automatic setup is done only when the starting point
     ++	is a remote-tracking branch and the new branch has the same name as the
     ++	remote branch. This option defaults to true.
     + 
     + branch.autoSetupRebase::
     + 	When a new branch is created with 'git branch', 'git switch' or 'git checkout'
     +
     + ## Documentation/git-branch.txt ##
     +@@ Documentation/git-branch.txt: The exact upstream branch is chosen depending on the optional argument:
     + itself as the upstream; `--track=inherit` means to copy the upstream
     + configuration of the start-point branch.
     + +
     +-`--track=direct` is the default when the start point is a remote-tracking branch.
     +-Set the branch.autoSetupMerge configuration variable to `false` if you
     +-want `git switch`, `git checkout` and `git branch` to always behave as if `--no-track`
     +-were given. Set it to `always` if you want this behavior when the
     +-start-point is either a local or remote-tracking branch. Set it to
     +-`inherit` if you want to copy the tracking configuration from the
     +-branch point.
     ++The branch.autoSetupMerge configuration variable specifies how `git switch`,
     ++`git checkout` and `git branch` should behave when neither `--track` nor
     ++`--no-track` are specified:
     +++
     ++The default option, `true`, behaves as though `--track=direct`
     ++were given whenever the start-point is a remote-tracking branch.
     ++`false` behaves as if `--no-track` were given. `always` behaves as though
     ++`--track=direct` were given. `inherit` behaves as though `--track=inherit`
     ++were given. `simple` behaves as though `--track=direct` were given only when
     ++the start-point is a remote-tracking branch and the new branch has the same
     ++name as the remote branch.
     + +
     + See linkgit:git-pull[1] and linkgit:git-config[1] for additional discussion on
     + how the `branch.<name>.remote` and `branch.<name>.merge` options are used.
     +
       ## branch.c ##
      @@ branch.c: static void setup_tracking(const char *new_ref, const char *orig_ref,
     + 			goto cleanup;
     + 		}
     + 
     ++	/*
     ++	 * This check does not apply to the BRANCH_TRACK_INHERIT
     ++	 * option; you can inherit one or more tracking entries
     ++	 * and the tracking.matches counter is not incremented.
     ++	 */
     + 	if (tracking.matches > 1)
       		die(_("not tracking: ambiguous information for ref %s"),
       		    orig_ref);
       
      +	if (track == BRANCH_TRACK_SIMPLE) {
     -+		// only track if remote branch name matches
     -+		// (tracking.srcs must contain only one entry from find_tracked_branch with this config)
     -+		if (strncmp(tracking.srcs->items[0].string, "refs/heads/", 11))
     -+			return;
     -+		if (strcmp(tracking.srcs->items[0].string + 11, new_ref))
     ++		/*
     ++		 * Only track if remote branch name matches.
     ++		 * Reaching into items[0].string is safe because
     ++		 * we know there is at least one and not more than
     ++		 * one entry (because not BRANCH_TRACK_INHERIT).
     ++		 */
     ++		const char *tracked_branch;
     ++		if (!skip_prefix(tracking.srcs->items[0].string,
     ++				 "refs/heads/", &tracked_branch) ||
     ++		    strcmp(tracked_branch, new_ref))
      +			return;
      +	}
      +
 2:  3fa56f1d2a0 ! 2:  c16a8fe01e7 t3200: tests for new branch.autosetupmerge option "simple"
     @@ Commit message
      
          The matching-name case needs to temporarily create
          an independent repo to fetch from, as the general
     -    strategy in these tests of using the local repo as
     -    the remote precludes locally branching with the same
     -    name as the "remote".
     +    strategy of using the local repo as the remote in these
     +    tests precludes locally branching with the same
     +    name as in the "remote".
      
          Signed-off-by: Tao Klerks <tao@klerks.biz>
      
 3:  39c14906e7b < -:  ----------- branch documentation: new autosetupmerge option "simple"