git/Documentation/git-replay.adoc

git-replay(1)
=============

NAME
----
git-replay - EXPERIMENTAL: Replay commits on a new base, works with bare repos too


SYNOPSIS
--------
[verse]
(EXPERIMENTAL!) 'git replay' ([--contained] --onto <newbase> | --advance <branch>) [--ref-action[=<mode>]] <revision-range>

DESCRIPTION
-----------

Takes a range of commits and replays them onto a new location. Leaves
the working tree and the index untouched. By default, updates the
relevant references using an atomic transaction (all refs update or
none). Use `--ref-action=print` to avoid automatic ref updates and
instead get update commands that can be piped to `git update-ref --stdin`
(see the <<output,OUTPUT>> section below).

THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.

OPTIONS
-------

--onto <newbase>::
	Starting point at which to create the new commits.  May be any
	valid commit, and not just an existing branch name.
+
When `--onto` is specified, the branch(es) in the revision range will be
updated to point at the new commits, similar to the way `git rebase --update-refs`
updates multiple branches in the affected range.

--advance <branch>::
	Starting point at which to create the new commits; must be a
	branch name.
+
The history is replayed on top of the <branch> and <branch> is updated to
point at the tip of the resulting history. This is different from `--onto`,
which uses the target only as a starting point without updating it.

--contained::
	Update all branches that point at commits in
	<revision-range>. Requires `--onto`.

--ref-action[=<mode>]::
	Control how references are updated. The mode can be:
+
--
	* `update` (default): Update refs directly using an atomic transaction.
	  All refs are updated or none are (all-or-nothing behavior).
	* `print`: Output update-ref commands for pipeline use. This is the
	  traditional behavior where output can be piped to `git update-ref --stdin`.
--
+
The default mode can be configured via the `replay.refAction` configuration variable.

<revision-range>::
	Range of commits to replay; see "Specifying Ranges" in
	linkgit:git-rev-parse[1]. In `--advance <branch>` mode, the
	range should have a single tip, so that it's clear to which tip the
	advanced <branch> should point.

:git-replay: 1
include::rev-list-options.adoc[]

[[output]]
OUTPUT
------

By default, or with `--ref-action=update`, this command produces no output on
success, as refs are updated directly using an atomic transaction.

When using `--ref-action=print`, the output is usable as input to
`git update-ref --stdin`. It is of the form:

	update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
	update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
	update refs/heads/branch3 ${NEW_branch3_HASH} ${OLD_branch3_HASH}

where the number of refs updated depends on the arguments passed and
the shape of the history being replayed.  When using `--advance`, the
number of refs updated is always one, but for `--onto`, it can be one
or more (rebasing multiple branches simultaneously is supported).

There is no stderr output on conflicts; see the <<exit-status,EXIT
STATUS>> section below.

[[exit-status]]
EXIT STATUS
-----------

For a successful, non-conflicted replay, the exit status is 0.  When
the replay has conflicts, the exit status is 1.  If the replay is not
able to complete (or start) due to some kind of error, the exit status
is something other than 0 or 1.

EXAMPLES
--------

To simply rebase `mybranch` onto `target`:

------------
$ git replay --onto target origin/main..mybranch
------------

The refs are updated atomically and no output is produced on success.

To see what would be updated without actually updating:

------------
$ git replay --ref-action=print --onto target origin/main..mybranch
update refs/heads/mybranch ${NEW_mybranch_HASH} ${OLD_mybranch_HASH}
------------

To cherry-pick the commits from mybranch onto target:

------------
$ git replay --advance target origin/main..mybranch
------------

Note that the first two examples replay the exact same commits and on
top of the exact same new base, they only differ in that the first
updates mybranch to point at the new commits and the second updates
target to point at them.

What if you have a stack of branches, one depending upon another, and
you'd really like to rebase the whole set?

------------
$ git replay --contained --onto origin/main origin/main..tipbranch
------------

All three branches (`branch1`, `branch2`, and `tipbranch`) are updated
atomically.

When calling `git replay`, one does not need to specify a range of
commits to replay using the syntax `A..B`; any range expression will
do:

------------
$ git replay --onto origin/main ^base branch1 branch2 branch3
------------

This will simultaneously rebase `branch1`, `branch2`, and `branch3`,
all commits they have since `base`, playing them on top of
`origin/main`. These three branches may have commits on top of `base`
that they have in common, but that does not need to be the case.

GIT
---
Part of the linkgit:git[1] suite