Command: git restack

Description

Available since v0.1.0.

git restack is a command used to fix abandoned commits.

Sometimes, when you do a rewrite operation (such as git commit --amend), the current commit is updated, but descendant commits are not moved to be based off of the updated current commit. These commits are said to be "abandoned".

Usage

Abandoned commits appear in the smartlog as descendant commits of grayed-out hidden commits, which have the ✕ icon. In the below example, the commit pointed to by the xyzzy branch is abandoned, because it's based on top of the Create baz commit, which has been rewritten.

$ git sl
⋮
◇ 86bdeac0 60d (master) Revert "Update foo"
┃
◯ ec6d42e8 9d Create bar
┣━┓
┃ ✕ 55122556 9d (rewritten as 4c4e08e9) Create baz
┃ ┃
┃ ◯ 431d09d1 9d (xyzzy) Create xyzzy
┣━┓
┃ ◯ 87b20a4b 9d Create qux
┃
● 4c4e08e9 1m Create baz, AMENDED

To restack all abandoned commits in your repository, run git restack:

$ git restack
Attempting rebase in-memory...
[1/1] Committed as: 477a8a18 Create xyzzy
branchless: processing 1 update: branch xyzzy
branchless: processing 1 rewritten commit
In-memory rebase succeeded.
Finished restacking commits.
No abandoned branches to restack.
branchless: running command: git checkout 4c4e08e97e929ddc491a6ffaec894880150040a7
branchless: processing 1 update: ref HEAD
HEAD is now at 4c4e08e Create baz, AMENDED
branchless: processing checkout
⋮
◇ 86bdeac0 60d (master) Revert "Update foo"
┃
◯ ec6d42e8 9d Create bar
┣━┓
┃ ◯ 87b20a4b 9d Create qux
┃
● 4c4e08e9 4m Create baz, AMENDED
┃
◯ 477a8a18 0s (xyzzy) Create xyzzy

Notice that the commit Create xyzzy, as well as the branch xyzzy pointing to it, have been relocated on top of the new commit Create baz, AMENDED. Since the old, rewritten version of Create baz no longer has any abandoned children, it no longer appears in the smartlog.

Note that restacking commits may require you to resolve merge conflicts which happen as a result of applying the abandoned commits on top of their destinations.

Restack warnings

If you run a command that results in abandoned commits, git-branchless will try to warn you by printing out a message:

$ git commit --amend -m 'Create baz, AMENDED'
branchless: processing 1 update: ref HEAD
branchless: processed commit: 4c4e08e9 Create baz, AMENDED
branchless: processing 1 rewritten commit
branchless: This operation abandoned 1 commit!
branchless: Consider running one of the following:
branchless:   - git restack: re-apply the abandoned commits/branches
branchless:     (this is most likely what you want to do)
branchless:   - git smartlog: assess the situation
branchless:   - git hide [<commit>...]: hide the commits from the smartlog
branchless:   - git undo: undo the operation
branchless:   - git config branchless.restack.warnAbandoned false: suppress this message
[detached HEAD 4c4e08e] Create baz, AMENDED
 Date: Thu Sep 30 10:58:23 2021 -0700
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 baz

You can apply one of the suggestions, such as running git restack.

Restacking only some commits

If you only want to restack some commits, you can specify a list of hidden commits as arguments to git restack. Only their children will be restacked. In the following example, Create xyzzy is restacked, but Create grault is not.

$ git sl
⋮
◇ 86bdeac0 60d (master) Revert "Update foo"
┃
◯ ec6d42e8 9d Create bar
┣━┓
┃ ✕ 55122556 9d (rewritten as 4c4e08e9) Create baz
┃ ┃
┃ ◯ 431d09d1 9d (xyzzy) Create xyzzy
┣━┓
┃ ✕ 87b20a4b 9d (rewritten as 98e1018c) Create qux
┃ ┃
┃ ◯ 8b45ee2c 9s Create grault
┣━┓
┃ ◯ 4c4e08e9 10m Create baz, AMENDED
┃
● 98e1018c 1s Create qux, AMENDED

$ git restack 55122556
Attempting rebase in-memory...
[1/1] Committed as: aab75d20 Create xyzzy
branchless: processing 1 update: branch xyzzy
branchless: processing 1 rewritten commit
In-memory rebase succeeded.
Finished restacking commits.
No abandoned branches to restack.
branchless: running command: git checkout 98e1018ceb5d8c7228bd7c631a92e990f7e1569c
branchless: processing 1 update: ref HEAD
HEAD is now at 98e1018 Create qux, AMENDED
branchless: processing checkout
⋮
◇ 86bdeac0 60d (master) Revert "Update foo"
┃
◯ ec6d42e8 9d Create bar
┣━┓
┃ ✕ 87b20a4b 9d (rewritten as 98e1018c) Create qux
┃ ┃
┃ ◯ 8b45ee2c 20s Create grault
┣━┓
┃ ◯ 4c4e08e9 10m Create baz, AMENDED
┃ ┃
┃ ◯ aab75d20 0s (xyzzy) Create xyzzy
┃
● 98e1018c 12s Create qux, AMENDED