| 1 | git-revert(1) |
| 2 | ============= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-revert - Revert some existing commits |
| 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
| 10 | [verse] |
| 11 | 'git revert' [--[no-]edit] [-n] [-m <parent-number>] [-s] [-S[<keyid>]] <commit>... |
| 12 | 'git revert' (--continue | --skip | --abort | --quit) |
| 13 | |
| 14 | DESCRIPTION |
| 15 | ----------- |
| 16 | |
| 17 | Given one or more existing commits, revert the changes that the |
| 18 | related patches introduce, and record some new commits that record |
| 19 | them. This requires your working tree to be clean (no modifications |
| 20 | from the HEAD commit). |
| 21 | |
| 22 | Note: 'git revert' is used to record some new commits to reverse the |
| 23 | effect of some earlier commits (often only a faulty one). If you want to |
| 24 | throw away all uncommitted changes in your working directory, you |
| 25 | should see linkgit:git-reset[1], particularly the `--hard` option. If |
| 26 | you want to extract specific files as they were in another commit, you |
| 27 | should see linkgit:git-restore[1], specifically the `--source` |
| 28 | option. Take care with these alternatives as |
| 29 | both will discard uncommitted changes in your working directory. |
| 30 | |
| 31 | See "Reset, restore and revert" in linkgit:git[1] for the differences |
| 32 | between the three commands. |
| 33 | |
| 34 | OPTIONS |
| 35 | ------- |
| 36 | <commit>...:: |
| 37 | Commits to revert. |
| 38 | For a more complete list of ways to spell commit names, see |
| 39 | linkgit:gitrevisions[7]. |
| 40 | Sets of commits can also be given but no traversal is done by |
| 41 | default, see linkgit:git-rev-list[1] and its `--no-walk` |
| 42 | option. |
| 43 | |
| 44 | -e:: |
| 45 | --edit:: |
| 46 | With this option, 'git revert' will let you edit the commit |
| 47 | message prior to committing the revert. This is the default if |
| 48 | you run the command from a terminal. |
| 49 | |
| 50 | -m parent-number:: |
| 51 | --mainline parent-number:: |
| 52 | Usually you cannot revert a merge because you do not know which |
| 53 | side of the merge should be considered the mainline. This |
| 54 | option specifies the parent number (starting from 1) of |
| 55 | the mainline and allows revert to reverse the change |
| 56 | relative to the specified parent. |
| 57 | + |
| 58 | Reverting a merge commit declares that you will never want the tree changes |
| 59 | brought in by the merge. As a result, later merges will only bring in tree |
| 60 | changes introduced by commits that are not ancestors of the previously |
| 61 | reverted merge. This may or may not be what you want. |
| 62 | + |
| 63 | See the link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for |
| 64 | more details. |
| 65 | |
| 66 | --no-edit:: |
| 67 | With this option, 'git revert' will not start the commit |
| 68 | message editor. |
| 69 | |
| 70 | --cleanup=<mode>:: |
| 71 | This option determines how the commit message will be cleaned up before |
| 72 | being passed on to the commit machinery. See linkgit:git-commit[1] for more |
| 73 | details. In particular, if the '<mode>' is given a value of `scissors`, |
| 74 | scissors will be appended to `MERGE_MSG` before being passed on in the case |
| 75 | of a conflict. |
| 76 | |
| 77 | -n:: |
| 78 | --no-commit:: |
| 79 | Usually the command automatically creates some commits with |
| 80 | commit log messages stating which commits were |
| 81 | reverted. This flag applies the changes necessary |
| 82 | to revert the named commits to your working tree |
| 83 | and the index, but does not make the commits. In addition, |
| 84 | when this option is used, your index does not have to match |
| 85 | the HEAD commit. The revert is done against the |
| 86 | beginning state of your index. |
| 87 | + |
| 88 | This is useful when reverting more than one commits' |
| 89 | effect to your index in a row. |
| 90 | |
| 91 | -S[<keyid>]:: |
| 92 | --gpg-sign[=<keyid>]:: |
| 93 | --no-gpg-sign:: |
| 94 | GPG-sign commits. The `keyid` argument is optional and |
| 95 | defaults to the committer identity; if specified, it must be |
| 96 | stuck to the option without a space. `--no-gpg-sign` is useful to |
| 97 | countermand both `commit.gpgSign` configuration variable, and |
| 98 | earlier `--gpg-sign`. |
| 99 | |
| 100 | -s:: |
| 101 | --signoff:: |
| 102 | Add a `Signed-off-by` trailer at the end of the commit message. |
| 103 | See the signoff option in linkgit:git-commit[1] for more information. |
| 104 | |
| 105 | --strategy=<strategy>:: |
| 106 | Use the given merge strategy. Should only be used once. |
| 107 | See the MERGE STRATEGIES section in linkgit:git-merge[1] |
| 108 | for details. |
| 109 | |
| 110 | -X<option>:: |
| 111 | --strategy-option=<option>:: |
| 112 | Pass the merge strategy-specific option through to the |
| 113 | merge strategy. See linkgit:git-merge[1] for details. |
| 114 | |
| 115 | include::rerere-options.adoc[] |
| 116 | |
| 117 | --reference:: |
| 118 | Instead of starting the body of the log message with "This |
| 119 | reverts <full-object-name-of-the-commit-being-reverted>.", |
| 120 | refer to the commit using "--pretty=reference" format |
| 121 | (cf. linkgit:git-log[1]). The `revert.reference` |
| 122 | configuration variable can be used to enable this option by |
| 123 | default. |
| 124 | |
| 125 | |
| 126 | SEQUENCER SUBCOMMANDS |
| 127 | --------------------- |
| 128 | include::sequencer.adoc[] |
| 129 | |
| 130 | EXAMPLES |
| 131 | -------- |
| 132 | `git revert HEAD~3`:: |
| 133 | |
| 134 | Revert the changes specified by the fourth last commit in HEAD |
| 135 | and create a new commit with the reverted changes. |
| 136 | |
| 137 | `git revert -n master~5..master~2`:: |
| 138 | |
| 139 | Revert the changes done by commits from the fifth last commit |
| 140 | in master (included) to the third last commit in master |
| 141 | (included), but do not create any commit with the reverted |
| 142 | changes. The revert only modifies the working tree and the |
| 143 | index. |
| 144 | |
| 145 | DISCUSSION |
| 146 | ---------- |
| 147 | |
| 148 | While git creates a basic commit message automatically, it is |
| 149 | _strongly_ recommended to explain why the original commit is being |
| 150 | reverted. |
| 151 | In addition, repeatedly reverting reverts will result in increasingly |
| 152 | unwieldy subject lines, for example 'Reapply "Reapply "<original-subject>""'. |
| 153 | Please consider rewording these to be shorter and more unique. |
| 154 | |
| 155 | CONFIGURATION |
| 156 | ------------- |
| 157 | |
| 158 | include::includes/cmd-config-section-all.adoc[] |
| 159 | |
| 160 | include::config/revert.adoc[] |
| 161 | |
| 162 | SEE ALSO |
| 163 | -------- |
| 164 | linkgit:git-cherry-pick[1] |
| 165 | |
| 166 | GIT |
| 167 | --- |
| 168 | Part of the linkgit:git[1] suite |