threads / discuss / 66598

switch/checkout stops halfway when it fails to write tracking config

Subject: switch/checkout stops halfway when it fails to write tracking config

## tl;dr

A fix for git switch leaving a half-switched worktree when tracking config can't be written has merged; a follow-up aims to make the whole switch atomic. Read the story.

replies: 8people: 3as markdown or json

井上司· Oct 20, 2026, 01:39 UTC · lore
1. What happened
When writing the tracking config fails (e.g. .git/config.lock exists) while
switch or checkout creates a new branch, the command exits with code 1 in the
middle of the switch. The worktree and index are already updated for the new
branch, but HEAD still points to the old branch. The user then sees unrelated
staged changes.
2. Reproduction
git init -q -b main up
cd up
echo one >file && git add file && git commit -q -m one
git branch feat
cd ..
git clone -q up work
cd up
git switch -q feat
echo two >>file && git commit -q -a -m two
cd ../work
git fetch -q
touch .git/config.lock
git switch feat; echo "exit=$?"
git symbolic-ref HEAD
git status --short

Output (git 2.43.0): error: could not lock config file .git/config: File exists error: unable to write upstream branch configuration hint: hint: After fixing the error cause you may try to fix up hint: the remote tracking information by invoking: hint: git branch --set-upstream-to=origin/refs/heads/feat exit=1 refs/heads/main M file

3. Expectation
I expected it to either complete the switch, or fail without changing anything.
4. Scope
The reproduction above uses DWIM (git switch feat). The same happens with
switch -c, checkout -b, and --track. With -C on another existing branch, that
branch is reset before the failure, so its old commits can only be found in
the reflog.
5. Root cause
update_refs_for_switch() -> create_branch() -> setup_tracking() fails to write
the config, and the code calls exit(1) in setup_tracking() (branch.c). At that
point the worktree and the branch have been changed, but HEAD has not. This
exit was introduced in 27852b2c53 (branch: report errors in tracking branch
setup, 2016-02-22).
6. Related
The wrong hint printed for the same failure is fixed separately in
<lore URL>. That patch does not fix this problem.
7. Next steps
I would like to work on a fix. Should checkout finish the switch and only
report the tracking error, or should it fail before touching the worktree?
Junio C Hamano· Oct 20, 2026, 04:11 UTC · re: 井上司 · lore

Re: switch/checkout stops halfway when it fails to write tracking config

井上司 <inoue.tsukasa.4@gmail.com> writes:
> 7. Next steps
> I would like to work on a fix. Should checkout finish the switch and only
> report the tracking error, or should it fail before touching the worktree?

Either would be an improvement over the reported behaviour, but if we can make it atomic "all-or-none" matter, that would be more preferrable than switching without setting up the tracking.

井上司· Oct 20, 2026, 06:33 UTC · re: Junio C Hamano · lore

Re: switch/checkout stops halfway when it fails to write tracking config

Thanks for the reply.

I agree with your point. However, implementing full atomicity now would be a large change, for two reasons:

- push -u, clone and fetch continue even when writing the tracking config
  fails, but setup_tracking() calls exit() and aborts the process.
- For full atomicity, we would need to undo the worktree, the ref and the
  config. We would also need to handle the die() calls in checkout.

So I propose to make setup_tracking() return an error instead of calling exit(), so that switch and checkout can behave like the other callers, and to leave full atomicity as a separate topic.

2026年10月20日(火) 13:11 Junio C Hamano <gitster@pobox.com>:
Show 10 quoted lines
>
> 井上司 <inoue.tsukasa.4@gmail.com> writes:
>
> > 7. Next steps
> > I would like to work on a fix. Should checkout finish the switch and only
> > report the tracking error, or should it fail before touching the worktree?
>
> Either would be an improvement over the reported behaviour, but if
> we can make it atomic "all-or-none" matter, that would be more
> preferrable than switching without setting up the tracking.
Junio C Hamano· Oct 21, 2026, 02:33 UTC · re: 井上司 · lore

Re: switch/checkout stops halfway when it fails to write tracking config

井上司 <inoue.tsukasa.4@gmail.com> writes:
Show 13 quoted lines
> Thanks for the reply.
>
> I agree with your point. However, implementing full atomicity now would
> be a large change, for two reasons:
>
> - push -u, clone and fetch continue even when writing the tracking config
>   fails, but setup_tracking() calls exit() and aborts the process.
> - For full atomicity, we would need to undo the worktree, the ref and the
>   config. We would also need to handle the die() calls in checkout.
>
> So I propose to make setup_tracking() return an error instead of calling
> exit(), so that switch and checkout can behave like the other callers,
> and to leave full atomicity as a separate topic.
Sounds like a good direction to go.
D. Ben Knoble· Oct 20, 2026, 13:06 UTC · re: 井上司 · lore

Re: switch/checkout stops halfway when it fails to write tracking config

On Mon, Oct 19, 2026 at 9:41 PM 井上司 <inoue.tsukasa.4@gmail.com> wrote:
Show 7 quoted lines
>
> 5. Root cause
> update_refs_for_switch() -> create_branch() -> setup_tracking() fails to write
> the config, and the code calls exit(1) in setup_tracking() (branch.c). At that
> point the worktree and the branch have been changed, but HEAD has not. This
> exit was introduced in 27852b2c53 (branch: report errors in tracking branch
> setup, 2016-02-22).

I can see where create_branch() is called prior to setting up HEAD, but I'm mildly confused about the index/wt updates prior to either! It seems to me that should be one of the last steps, hm. Unfortunately, I'm having a hard time finding the responsible code outside of the "merge" case (which probably has a similar issue).

-- 
D. Ben Knoble
井上司· Oct 20, 2026, 15:08 UTC · re: D. Ben Knoble · lore

Re: switch/checkout stops halfway when it fails to write tracking config

Show 5 quoted lines
> I can see where create_branch() is called prior to setting up HEAD,
> but I'm mildly confused about the index/wt updates prior to either! It
> seems to me that should be one of the last steps, hm. Unfortunately,
> I'm having a hard time finding the responsible code outside of the
> "merge" case (which probably has a similar issue).
- merge_working_tree() updates the worktree and the index. It is called
  from switch_branches() on every branch switch, not only with -m,
  because do_merge starts at 1.
- The "merge" here is not -m. It is the 2-way merge in unpack_trees().
  -m only adds an autostash step for when that 2-way merge fails.
- The order is: update the worktree, create the ref, write the tracking
  config (which fails), then update HEAD. As you noticed, the worktree
  and index are updated before the ref and HEAD, so a failure later
  leaves those changes in place.
- As you guessed, the -m case has the same problem. I tried
  "git switch -m -c y origin/main" with the lock present (v2.56.0 plus
  my hint patch, which only changes the hint text). It stops in the same
  place. If local changes conflict, HEAD stays on main, the file is left
  conflicted, and the changes remain in the stash.
- Running the same command again in that conflicted state stops with
  "a branch named 'y' already exists". Switching to the existing branch
  y stops with "you need to resolve your current index first"
  (checkout.c:887 in v2.56.0). Neither run changes the state.
2026年10月20日(火) 22:07 D. Ben Knoble <ben.knoble@gmail.com>:
Show 18 quoted lines
>
> On Mon, Oct 19, 2026 at 9:41 PM 井上司 <inoue.tsukasa.4@gmail.com> wrote:
> >
> > 5. Root cause
> > update_refs_for_switch() -> create_branch() -> setup_tracking() fails to write
> > the config, and the code calls exit(1) in setup_tracking() (branch.c). At that
> > point the worktree and the branch have been changed, but HEAD has not. This
> > exit was introduced in 27852b2c53 (branch: report errors in tracking branch
> > setup, 2016-02-22).
>
> I can see where create_branch() is called prior to setting up HEAD,
> but I'm mildly confused about the index/wt updates prior to either! It
> seems to me that should be one of the last steps, hm. Unfortunately,
> I'm having a hard time finding the responsible code outside of the
> "merge" case (which probably has a similar issue).
>
> --
> D. Ben Knoble
D. Ben Knoble· Oct 22, 2026, 12:48 UTC · re: 井上司 · lore

Re: switch/checkout stops halfway when it fails to write tracking config

On Tue, Oct 20, 2026 at 11:09 AM 井上司 <inoue.tsukasa.4@gmail.com> wrote:
Show 11 quoted lines
>
> > I can see where create_branch() is called prior to setting up HEAD,
> > but I'm mildly confused about the index/wt updates prior to either! It
> > seems to me that should be one of the last steps, hm. Unfortunately,
> > I'm having a hard time finding the responsible code outside of the
> > "merge" case (which probably has a similar issue).
>
>
> - merge_working_tree() updates the worktree and the index. It is called
>   from switch_branches() on every branch switch, not only with -m,
>   because do_merge starts at 1.

Ah, thanks, I think that's what I overlooked. I wonder if it's a royal pain to make that step and the index step come later in the sequence? But that is more of a band-aid than a proper atomicity fix.

Show 15 quoted lines
> - The "merge" here is not -m. It is the 2-way merge in unpack_trees().
>   -m only adds an autostash step for when that 2-way merge fails.
> - The order is: update the worktree, create the ref, write the tracking
>   config (which fails), then update HEAD. As you noticed, the worktree
>   and index are updated before the ref and HEAD, so a failure later
>   leaves those changes in place.
> - As you guessed, the -m case has the same problem. I tried
>   "git switch -m -c y origin/main" with the lock present (v2.56.0 plus
>   my hint patch, which only changes the hint text). It stops in the same
>   place. If local changes conflict, HEAD stays on main, the file is left
>   conflicted, and the changes remain in the stash.
> - Running the same command again in that conflicted state stops with
>   "a branch named 'y' already exists". Switching to the existing branch
>   y stops with "you need to resolve your current index first"
>   (checkout.c:887 in v2.56.0). Neither run changes the state.
[trimmed repeated quoted content]
-- 
D. Ben Knoble
井上司· Oct 22, 2026, 23:48 UTC · re: D. Ben Knoble · lore

Re: switch/checkout stops halfway when it fails to write tracking config

> I wonder if it's a royal pain to make that step and the index step come
> later in the sequence? But that is more of a band-aid than a proper
> atomicity fix.

I checked this against the code and tried two cases. I used a build of the series (2.56.0.217.gfcc73a773a, master plus the series at https://lore.kernel.org/git/pull.2275.git.1792637495.gitgitgadget@gmail.com/).

Why the worktree update comes first: switch_branches() calls merge_working_tree() before update_refs_for_switch(). If merge_working_tree() fails, the function returns before the ref is created or HEAD is updated.

Case A: a local change to f conflicts with the switch, and I ran "git switch -c y origin/main". It fails with "Your local changes to the following files would be overwritten by checkout", exit 1. HEAD stays on main, the local change is kept, no ref y is created, and branch.y.remote is not set. Nothing is left behind.

If the ref and the tracking config were written first, this failure would leave a new branch and its config behind. Moving the worktree update later would move that cleanup into this case, so I agree that moving the step is a band-aid rather than atomicity.

Some failures can still happen after the worktree update:

Case B: with .git/refs/heads/y.lock present, "git switch -c y origin/main" fails with "fatal: cannot lock ref 'refs/heads/y'", exit 128. HEAD stays on main, and the switch's change to f stays staged. This is the same kind of halfway state. Updating HEAD can also fail: checkout.c:1027-1028 calls die(_("unable to update HEAD")).

The tracking-config failure is handled by the series linked above: the switch finishes and exits 0. Full atomicity, which would also undo the worktree and the ref when a later step fails, is left for a separate topic.

2026年10月22日(木) 21:48 D. Ben Knoble <ben.knoble@gmail.com>:
Show 38 quoted lines
>
> On Tue, Oct 20, 2026 at 11:09 AM 井上司 <inoue.tsukasa.4@gmail.com> wrote:
> >
> > > I can see where create_branch() is called prior to setting up HEAD,
> > > but I'm mildly confused about the index/wt updates prior to either! It
> > > seems to me that should be one of the last steps, hm. Unfortunately,
> > > I'm having a hard time finding the responsible code outside of the
> > > "merge" case (which probably has a similar issue).
> >
> >
> > - merge_working_tree() updates the worktree and the index. It is called
> >   from switch_branches() on every branch switch, not only with -m,
> >   because do_merge starts at 1.
>
> Ah, thanks, I think that's what I overlooked. I wonder if it's a royal
> pain to make that step and the index step come later in the sequence?
> But that is more of a band-aid than a proper atomicity fix.
>
> > - The "merge" here is not -m. It is the 2-way merge in unpack_trees().
> >   -m only adds an autostash step for when that 2-way merge fails.
> > - The order is: update the worktree, create the ref, write the tracking
> >   config (which fails), then update HEAD. As you noticed, the worktree
> >   and index are updated before the ref and HEAD, so a failure later
> >   leaves those changes in place.
> > - As you guessed, the -m case has the same problem. I tried
> >   "git switch -m -c y origin/main" with the lock present (v2.56.0 plus
> >   my hint patch, which only changes the hint text). It stops in the same
> >   place. If local changes conflict, HEAD stays on main, the file is left
> >   conflicted, and the changes remain in the stash.
> > - Running the same command again in that conflicted state stops with
> >   "a branch named 'y' already exists". Switching to the existing branch
> >   y stops with "you need to resolve your current index first"
> >   (checkout.c:887 in v2.56.0). Neither run changes the state.
>
> [trimmed repeated quoted content]
>
> --
> D. Ben Knoble
井上司· Nov 8, 2026, 12:54 UTC · re: 井上司 · lore

Re: switch/checkout stops halfway when it fails to write tracking config

To: Junio C Hamano <gitster@pobox.com>
Cc: git@vger.kernel.org, "D. Ben Knoble" <ben.knoble@gmail.com>,
Patrick Steinhardt <ps@pks.im>
Subject: Re: switch/checkout stops halfway when it fails to write
tracking config
In-Reply-To: <xmqqecdjsryk.fsf@gitster.g>
Junio C Hamano <gitster@pobox.com> writes:
> > ... and to leave full atomicity as a separate topic.
>
> Sounds like a good direction to go.

Thanks for merging ti/checkout-track-failure, and thanks to Ben for the questions in this thread.

I'd like to work on the all-or-none switch now. Today switch_branches() updates the worktree first, then creates the branch ref, writes the tracking config and updates HEAD, so a failure after the first step leaves the worktree switched. I looked at two ways to fix this:

A. Put the branch ref and HEAD in one transaction, prepare it before
   merge_working_tree(), and commit or abort it afterwards.
B. Prepare that transaction only as a check and abort it, then do the
   real updates after the worktree update, as today.

I tried both with "git update-ref --stdin" on current master, files and reftable:

 - In both, a stale branch lock or a reference-transaction hook rejecting
   at "prepared" stops the switch before the worktree changes.
 - With A, every other ref update in a reftable repository fails while
   the transaction is held, and with files a commit from another process
   fails on HEAD.lock. The -m autostash steps fail too, because they
   update HEAD.
 - A also has to put the branch and HEAD in one transaction, which runs
   into a reftable reflog bug I reported separately:
   https://lore.kernel.org/git/CAP8tz2L3Dfhd+ec4+SFkZgXmzQnBg+3Y0REAV+1Hf5X415qnfw@mail.gmail.com/
 - With B nothing is locked during the worktree update, so -m and other
   processes work as before. A branch created by another process between
   the check and the commit still leaves the switch halfway, and hooks see
   the check as "prepared" followed by "aborted".

So I'd like to go with B. The tracking config would be written before the worktree update and removed if a later step fails. For -C on the current branch HEAD does not change, so it would be left out of the check.

Does B sound acceptable, given that it does not cover the race with another process?

Thanks, Tsukasa

← back to recent threads