Documentation/git-history.adoc

git-history(1)
==============

NAME
----
git-history - EXPERIMENTAL: Rewrite history

SYNOPSIS
--------
[synopsis]
git history reword <commit> [--ref-action=(branches|head|print)]

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

Rewrite history by rearranging or modifying specific commits in the
history.

THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.

This command is related to linkgit:git-rebase[1] in that both commands can be
used to rewrite history. There are a couple of major differences though:

* linkgit:git-history[1] can work in a bare repository as it does not need to
  touch either the index or the worktree.
* linkgit:git-history[1] does not execute any linkgit:githooks[5] at the
  current point in time. This may change in the future.
* linkgit:git-history[1] by default updates all branches that are descendants
  of the original commit to point to the rewritten commit.

Overall, linkgit:git-history[1] aims to provide a more opinionated way to modify
your commit history that is simpler to use compared to linkgit:git-rebase[1] in
general.

Use linkgit:git-rebase[1] if you want to reapply a range of commits onto a
different base, or interactive rebases if you want to edit a range of commits
at once.

LIMITATIONS
-----------

This command does not (yet) work with histories that contain merges. You
should use linkgit:git-rebase[1] with the `--rebase-merges` flag instead.

Furthermore, the command does not support operations that can result in merge
conflicts. This limitation is by design as history rewrites are not intended to
be stateful operations. The limitation can be lifted once (if) Git learns about
first-class conflicts.

COMMANDS
--------

The following commands are available to rewrite history in different ways:

`reword <commit>`::
	Rewrite the commit message of the specified commit. All the other
	details of this commit remain unchanged. This command will spawn an
	editor with the current message of that commit.

OPTIONS
-------

`--ref-action=(branches|head|print)`::
	Control which references will be updated by the command, if any. With
	`branches`, all local branches that point to commits which are
	descendants of the original commit will be rewritten. With `head`, only
	the current `HEAD` reference will be rewritten. With `print`, all
	updates as they would be performed with `branches` are printed in a
	format that can be consumed by linkgit:git-update-ref[1].

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