git/Documentation/git-revert.txt

169 lines
5.3 KiB
Text
Raw Normal View History

git-revert(1)
=============
NAME
----
git-revert - Revert some existing commits
SYNOPSIS
--------
[verse]
'git revert' [--[no-]edit] [-n] [-m <parent-number>] [-s] [-S[<keyid>]] <commit>...
'git revert' (--continue | --skip | --abort | --quit)
DESCRIPTION
-----------
Given one or more existing commits, revert the changes that the
related patches introduce, and record some new commits that record
them. This requires your working tree to be clean (no modifications
from the HEAD commit).
Note: 'git revert' is used to record some new commits to reverse the
effect of some earlier commits (often only a faulty one). If you want to
throw away all uncommitted changes in your working directory, you
should see linkgit:git-reset[1], particularly the `--hard` option. If
you want to extract specific files as they were in another commit, you
should see linkgit:git-restore[1], specifically the `--source`
option. Take care with these alternatives as
both will discard uncommitted changes in your working directory.
checkout: split part of it to new command 'restore' Previously the switching branch business of 'git checkout' becomes a new command 'switch'. This adds the restore command for the checking out paths path. Similar to git-switch, a new man page is added to describe what the command will become. The implementation will be updated shortly to match the man page. A couple main differences from 'git checkout <paths>': - 'restore' by default will only update worktree. This matters more when --source is specified ('checkout <tree> <paths>' updates both worktree and index). - 'restore --staged' can be used to restore the index. This command overlaps with 'git reset <paths>'. - both worktree and index could also be restored at the same time (from a tree) when both --staged and --worktree are specified. This overlaps with 'git checkout <tree> <paths>' - default source for restoring worktree and index is the index and HEAD respectively. A different (tree) source could be specified as with --source (*). - when both index and worktree are restored, --source must be specified since the default source for these two individual targets are different (**) - --no-overlay is enabled by default, if an entry is missing in the source, restoring means deleting the entry (*) I originally went with --from instead of --source. I still think --from is a better name. The short option -f however is already taken by force. And I do think short option is good to have, e.g. to write -s@ or -s@^ instead of --source=HEAD. (**) If you sit down and think about it, moving worktree's source from the index to HEAD makes sense, but nobody is really thinking it through when they type the commands. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-04-25 09:45:45 +00:00
See "Reset, restore and revert" in linkgit:git[1] for the differences
between the three commands.
OPTIONS
-------
<commit>...::
Commits to revert.
For a more complete list of ways to spell commit names, see
linkgit:gitrevisions[7].
Sets of commits can also be given but no traversal is done by
default, see linkgit:git-rev-list[1] and its `--no-walk`
option.
-e::
--edit::
With this option, 'git revert' will let you edit the commit
message prior to committing the revert. This is the default if
you run the command from a terminal.
-m parent-number::
--mainline parent-number::
Usually you cannot revert a merge because you do not know which
side of the merge should be considered the mainline. This
option specifies the parent number (starting from 1) of
the mainline and allows revert to reverse the change
relative to the specified parent.
+
Reverting a merge commit declares that you will never want the tree changes
brought in by the merge. As a result, later merges will only bring in tree
changes introduced by commits that are not ancestors of the previously
reverted merge. This may or may not be what you want.
+
See the link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for
more details.
--no-edit::
With this option, 'git revert' will not start the commit
message editor.
--cleanup=<mode>::
This option determines how the commit message will be cleaned up before
being passed on to the commit machinery. See linkgit:git-commit[1] for more
details. In particular, if the '<mode>' is given a value of `scissors`,
scissors will be appended to `MERGE_MSG` before being passed on in the case
of a conflict.
-n::
--no-commit::
Usually the command automatically creates some commits with
commit log messages stating which commits were
reverted. This flag applies the changes necessary
to revert the named commits to your working tree
and the index, but does not make the commits. In addition,
when this option is used, your index does not have to match
the HEAD commit. The revert is done against the
beginning state of your index.
+
This is useful when reverting more than one commits'
effect to your index in a row.
-S[<keyid>]::
--gpg-sign[=<keyid>]::
--no-gpg-sign::
GPG-sign commits. The `keyid` argument is optional and
defaults to the committer identity; if specified, it must be
stuck to the option without a space. `--no-gpg-sign` is useful to
countermand both `commit.gpgSign` configuration variable, and
earlier `--gpg-sign`.
-s::
--signoff::
Documentation: stylistically normalize references to Signed-off-by: Ted reported an old typo in the git-commit.txt and merge-options.txt. Namely, the phrase "Signed-off-by line" was used without either a definite nor indefinite article. Upon examination, it seems that the documentation (including items in Documentation/, but also option help strings) have been quite inconsistent on usage when referring to `Signed-off-by`. First, very few places used a definite or indefinite article with the phrase "Signed-off-by line", but that was the initial typo that led to this investigation. So, normalize using either an indefinite or definite article consistently. The original phrasing, in Commit 3f971fc425b (Documentation updates, 2005-08-14), is "Add Signed-off-by line". Commit 6f855371a53 (Add --signoff, --check, and long option-names. 2005-12-09) switched to using "Add `Signed-off-by:` line", but didn't normalize the former commit to match. Later commits seem to have cut and pasted from one or the other, which is likely how the usage became so inconsistent. Junio stated on the git mailing list in <xmqqy2k1dfoh.fsf@gitster.c.googlers.com> a preference to leave off the colon. Thus, prefer `Signed-off-by` (with backticks) for the documentation files and Signed-off-by (without backticks) for option help strings. Additionally, Junio argued that "trailer" is now the standard term to refer to `Signed-off-by`, saying that "becomes plenty clear that we are not talking about any random line in the log message". As such, prefer "trailer" over "line" anywhere the former word fits. However, leave alone those few places in documentation that use Signed-off-by to refer to the process (rather than the specific trailer), or in places where mail headers are generally discussed in comparison with Signed-off-by. Reported-by: "Theodore Y. Ts'o" <tytso@mit.edu> Signed-off-by: Bradley M. Kuhn <bkuhn@sfconservancy.org> Acked-by: Taylor Blau <me@ttaylorr.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-10-20 01:03:55 +00:00
Add a `Signed-off-by` trailer at the end of the commit message.
See the signoff option in linkgit:git-commit[1] for more information.
--strategy=<strategy>::
Use the given merge strategy. Should only be used once.
See the MERGE STRATEGIES section in linkgit:git-merge[1]
for details.
-X<option>::
--strategy-option=<option>::
Pass the merge strategy-specific option through to the
merge strategy. See linkgit:git-merge[1] for details.
include::rerere-options.txt[]
revert: optionally refer to commit in the "reference" format A typical "git revert" commit uses the full title of the original commit in its title, and starts its body of the message with: This reverts commit 8fa7f667cf61386257c00d6e954855cc3215ae91. This does not encourage the best practice of describing not just "what" (i.e. "Revert X" on the title says what we did) but "why" (i.e. and it does not say why X was undesirable). We can instead phrase this first line of the body to be more like This reverts commit 8fa7f667 (do this and that, 2022-04-25) so that the title does not have to be Revert "do this and that" We can instead use the title to describe "why" we are reverting the original commit. Introduce the "--reference" option to "git revert", and also the revert.reference configuration variable, which defaults to false, to tweak the title and the first line of the draft commit message for when creating a "revert" commit. When this option is in use, the first line of the pre-filled editor buffer becomes a comment line that tells the user to say _why_. If the user exits the editor without touching this line by mistake, what we prepare to become the first line of the body, i.e. "This reverts commit 8fa7f667 (do this and that, 2022-04-25)", ends up to be the title of the resulting commit. This behaviour is designed to help such a user to identify such a revert in "git log --oneline" easily so that it can be further reworded with "git rebase -i" later. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-05-27 06:01:39 +00:00
--reference::
Instead of starting the body of the log message with "This
reverts <full object name of the commit being reverted>.",
refer to the commit using "--pretty=reference" format
(cf. linkgit:git-log[1]). The `revert.reference`
configuration variable can be used to enable this option by
default.
SEQUENCER SUBCOMMANDS
---------------------
include::sequencer.txt[]
EXAMPLES
--------
`git revert HEAD~3`::
Revert the changes specified by the fourth last commit in HEAD
and create a new commit with the reverted changes.
docs: stop using asciidoc no-inline-literal In asciidoc 7, backticks like `foo` produced a typographic effect, but did not otherwise affect the syntax. In asciidoc 8, backticks introduce an "inline literal" inside which markup is not interpreted. To keep compatibility with existing documents, asciidoc 8 has a "no-inline-literal" attribute to keep the old behavior. We enabled this so that the documentation could be built on either version. It has been several years now, and asciidoc 7 is no longer in wide use. We can now decide whether or not we want inline literals on their own merits, which are: 1. The source is much easier to read when the literal contains punctuation. You can use `master~1` instead of `master{tilde}1`. 2. They are less error-prone. Because of point (1), we tend to make mistakes and forget the extra layer of quoting. This patch removes the no-inline-literal attribute from the Makefile and converts every use of backticks in the documentation to an inline literal (they must be cleaned up, or the example above would literally show "{tilde}" in the output). Problematic sites were found by grepping for '`.*[{\\]' and examined and fixed manually. The results were then verified by comparing the output of "html2text" on the set of generated html pages. Doing so revealed that in addition to making the source more readable, this patch fixes several formatting bugs: - HTML rendering used the ellipsis character instead of literal "..." in code examples (like "git log A...B") - some code examples used the right-arrow character instead of '->' because they failed to quote - api-config.txt did not quote tilde, and the resulting HTML contained a bogus snippet like: <tt><sub></tt> foo <tt></sub>bar</tt> which caused some parsers to choke and omit whole sections of the page. - git-commit.txt confused ``foo`` (backticks inside a literal) with ``foo'' (matched double-quotes) - mentions of `A U Thor <author@example.com>` used to erroneously auto-generate a mailto footnote for author@example.com - the description of --word-diff=plain incorrectly showed the output as "[-removed-] and {added}", not "{+added+}". - using "prime" notation like: commit `C` and its replacement `C'` confused asciidoc into thinking that everything between the first backtick and the final apostrophe were meant to be inside matched quotes - asciidoc got confused by the escaping of some of our asterisks. In particular, `credential.\*` and `credential.<url>.\*` properly escaped the asterisk in the first case, but literally passed through the backslash in the second case. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-04-26 08:51:57 +00:00
`git revert -n master~5..master~2`::
Revert the changes done by commits from the fifth last commit
in master (included) to the third last commit in master
(included), but do not create any commit with the reverted
changes. The revert only modifies the working tree and the
index.
DISCUSSION
----------
While git creates a basic commit message automatically, it is
_strongly_ recommended to explain why the original commit is being
reverted.
In addition, repeatedly reverting reverts will result in increasingly
unwieldy subject lines, for example 'Reapply "Reapply "<original subject>""'.
Please consider rewording these to be shorter and more unique.
CONFIGURATION
-------------
include::includes/cmd-config-section-all.txt[]
include::config/revert.txt[]
SEE ALSO
--------
linkgit:git-cherry-pick[1]
GIT
---
Part of the linkgit:git[1] suite