blob: 8f3300c683a7bf8ee34792eab1732dc21cec991a [file] [log] [blame]
Elijah Newrenf920b022023-11-24 12:10:31 +01001git-replay(1)
2=============
3
4NAME
5----
6git-replay - EXPERIMENTAL: Replay commits on a new base, works with bare repos too
7
8
9SYNOPSIS
10--------
11[verse]
Elijah Newrenc4611132023-11-24 12:10:42 +010012(EXPERIMENTAL!) 'git replay' ([--contained] --onto <newbase> | --advance <branch>) <revision-range>...
Elijah Newrenf920b022023-11-24 12:10:31 +010013
14DESCRIPTION
15-----------
16
Elijah Newren3916ec32023-11-24 12:10:40 +010017Takes ranges of commits and replays them onto a new location. Leaves
Elijah Newren81613be2023-11-24 12:10:39 +010018the working tree and the index untouched, and updates no references.
19The output of this command is meant to be used as input to
Elijah Newren3916ec32023-11-24 12:10:40 +010020`git update-ref --stdin`, which would update the relevant branches
21(see the OUTPUT section below).
Elijah Newrenf920b022023-11-24 12:10:31 +010022
23THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
24
25OPTIONS
26-------
27
28--onto <newbase>::
29 Starting point at which to create the new commits. May be any
30 valid commit, and not just an existing branch name.
Elijah Newren3916ec32023-11-24 12:10:40 +010031+
Elijah Newren22d99f02023-11-24 12:10:41 +010032When `--onto` is specified, the update-ref command(s) in the output will
33update the branch(es) in the revision range to point at the new
34commits, similar to the way how `git rebase --update-refs` updates
35multiple branches in the affected range.
36
37--advance <branch>::
38 Starting point at which to create the new commits; must be a
39 branch name.
40+
41When `--advance` is specified, the update-ref command(s) in the output
42will update the branch passed as an argument to `--advance` to point at
43the new commits (in other words, this mimics a cherry-pick operation).
Elijah Newren3916ec32023-11-24 12:10:40 +010044
45<revision-range>::
Elijah Newren22d99f02023-11-24 12:10:41 +010046 Range of commits to replay. More than one <revision-range> can
47 be passed, but in `--advance <branch>` mode, they should have
48 a single tip, so that it's clear where <branch> should point
Yehezkel Bernatf412d722024-04-14 22:08:02 +000049 to. See "Specifying Ranges" in linkgit:git-rev-parse[1] and the
Elijah Newren22d99f02023-11-24 12:10:41 +010050 "Commit Limiting" options below.
Elijah Newren3916ec32023-11-24 12:10:40 +010051
52include::rev-list-options.txt[]
53
54OUTPUT
55------
56
57When there are no conflicts, the output of this command is usable as
58input to `git update-ref --stdin`. It is of the form:
59
60 update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
61 update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
62 update refs/heads/branch3 ${NEW_branch3_HASH} ${OLD_branch3_HASH}
63
64where the number of refs updated depends on the arguments passed and
Elijah Newren22d99f02023-11-24 12:10:41 +010065the shape of the history being replayed. When using `--advance`, the
66number of refs updated is always one, but for `--onto`, it can be one
67or more (rebasing multiple branches simultaneously is supported).
Elijah Newrenf920b022023-11-24 12:10:31 +010068
69EXIT STATUS
70-----------
71
72For a successful, non-conflicted replay, the exit status is 0. When
73the replay has conflicts, the exit status is 1. If the replay is not
74able to complete (or start) due to some kind of error, the exit status
75is something other than 0 or 1.
76
Elijah Newren3916ec32023-11-24 12:10:40 +010077EXAMPLES
78--------
79
80To simply rebase `mybranch` onto `target`:
81
82------------
83$ git replay --onto target origin/main..mybranch
84update refs/heads/mybranch ${NEW_mybranch_HASH} ${OLD_mybranch_HASH}
85------------
86
Elijah Newren22d99f02023-11-24 12:10:41 +010087To cherry-pick the commits from mybranch onto target:
88
89------------
90$ git replay --advance target origin/main..mybranch
91update refs/heads/target ${NEW_target_HASH} ${OLD_target_HASH}
92------------
93
94Note that the first two examples replay the exact same commits and on
95top of the exact same new base, they only differ in that the first
96provides instructions to make mybranch point at the new commits and
97the second provides instructions to make target point at them.
98
Elijah Newrenc4611132023-11-24 12:10:42 +010099What if you have a stack of branches, one depending upon another, and
100you'd really like to rebase the whole set?
101
102------------
103$ git replay --contained --onto origin/main origin/main..tipbranch
104update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
105update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
106update refs/heads/tipbranch ${NEW_tipbranch_HASH} ${OLD_tipbranch_HASH}
107------------
108
Elijah Newren3916ec32023-11-24 12:10:40 +0100109When calling `git replay`, one does not need to specify a range of
110commits to replay using the syntax `A..B`; any range expression will
111do:
112
113------------
114$ git replay --onto origin/main ^base branch1 branch2 branch3
115update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
116update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
117update refs/heads/branch3 ${NEW_branch3_HASH} ${OLD_branch3_HASH}
118------------
119
120This will simultaneously rebase `branch1`, `branch2`, and `branch3`,
121all commits they have since `base`, playing them on top of
122`origin/main`. These three branches may have commits on top of `base`
123that they have in common, but that does not need to be the case.
124
Elijah Newrenf920b022023-11-24 12:10:31 +0100125GIT
126---
127Part of the linkgit:git[1] suite