| 1 | git-history(1) |
| 2 | ============== |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-history - EXPERIMENTAL: Rewrite history |
| 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
| 10 | [synopsis] |
| 11 | git history drop <commit> [--dry-run] [--update-refs=(branches|head)] [--empty=(drop|keep|abort)] |
| 12 | git history fixup <commit> [--dry-run] [--update-refs=(branches|head)] [--reedit-message] [--empty=(drop|keep|abort)] |
| 13 | git history reword <commit> [--dry-run] [--update-refs=(branches|head)] |
| 14 | git history split <commit> [--dry-run] [--update-refs=(branches|head)] [--] [<pathspec>...] |
| 15 | git history squash [--dry-run] [--update-refs=(branches|head)] [--reedit-message] <revision-range> |
| 16 | |
| 17 | DESCRIPTION |
| 18 | ----------- |
| 19 | |
| 20 | Rewrite history by rearranging or modifying specific commits in the |
| 21 | history. |
| 22 | |
| 23 | THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE. |
| 24 | |
| 25 | This command is related to linkgit:git-rebase[1] in that both commands can be |
| 26 | used to rewrite history. There are a couple of major differences though: |
| 27 | |
| 28 | * Most subcommands of linkgit:git-history[1] can work in a bare repository as |
| 29 | they do not need to touch either the index or the worktree. The `fixup` |
| 30 | subcommand is an exception to this, as it reads staged changes from the index. |
| 31 | * linkgit:git-history[1] does not execute any linkgit:githooks[5] at the |
| 32 | current point in time. This may change in the future. |
| 33 | * linkgit:git-history[1] by default updates all branches that are descendants |
| 34 | of the original commit to point to the rewritten commit. |
| 35 | |
| 36 | Overall, linkgit:git-history[1] aims to provide a more opinionated way to modify |
| 37 | your commit history that is simpler to use compared to linkgit:git-rebase[1] in |
| 38 | general. |
| 39 | |
| 40 | Use linkgit:git-rebase[1] if you want to reapply a range of commits onto a |
| 41 | different base, or interactive rebases if you want to edit a range of commits |
| 42 | at once. |
| 43 | |
| 44 | LIMITATIONS |
| 45 | ----------- |
| 46 | |
| 47 | This command does not (yet) replay merge commits onto the rewritten |
| 48 | history: if a commit that would be replayed is a merge, the operation is |
| 49 | rejected, and you should use linkgit:git-rebase[1] with the |
| 50 | `--rebase-merges` flag instead. The `squash` subcommand can still fold a |
| 51 | merge that lies inside the range, as long as the range has a single base. |
| 52 | |
| 53 | Furthermore, the command does not support operations that can result in merge |
| 54 | conflicts. This limitation is by design as history rewrites are not intended to |
| 55 | be stateful operations. The limitation can be lifted once (if) Git learns about |
| 56 | first-class conflicts. |
| 57 | |
| 58 | When using `fixup` with `--empty=drop`, dropping the root commit is not yet |
| 59 | supported. Likewise, `drop` cannot remove the root commit or a merge commit. |
| 60 | |
| 61 | COMMANDS |
| 62 | -------- |
| 63 | |
| 64 | The following commands are available to rewrite history in different ways: |
| 65 | |
| 66 | `drop <commit>`:: |
| 67 | Remove the specified commit from the history. All descendants of the |
| 68 | commit are replayed directly onto its parent. |
| 69 | + |
| 70 | The root commit cannot be dropped as that may lead to edge cases where refs |
| 71 | end up with no commits anymore. Merge commits cannot be dropped either; see |
| 72 | LIMITATIONS. |
| 73 | + |
| 74 | If `HEAD` points at a commit that is to be rewritten, the index and working |
| 75 | tree are updated to match the new `HEAD`. The command aborts before any |
| 76 | references are updated in case local modifications would be overwritten. |
| 77 | + |
| 78 | If replaying any descendant would result in a conflict, the command aborts |
| 79 | with an error. |
| 80 | |
| 81 | `fixup <commit>`:: |
| 82 | Apply the currently staged changes to the specified commit. This is |
| 83 | similar in nature to `git commit --fixup=<commit>` followed by `git |
| 84 | rebase --autosquash <commit>~`. Changes are applied to the target |
| 85 | commit by performing a three-way merge between the HEAD commit, the |
| 86 | target commit and the tree generated from staged changes. |
| 87 | + |
| 88 | The commit message and authorship of the target commit are preserved by |
| 89 | default, unless you specify `--reedit-message`. |
| 90 | + |
| 91 | If applying the staged changes would result in a conflict, the command |
| 92 | aborts with an error. All branches that are descendants of the original |
| 93 | commit are updated to point to the rewritten history. |
| 94 | |
| 95 | `reword <commit>`:: |
| 96 | Rewrite the commit message of the specified commit. All the other |
| 97 | details of this commit remain unchanged. This command will spawn an |
| 98 | editor with the current message of that commit. |
| 99 | |
| 100 | `split <commit> [--] [<pathspec>...]`:: |
| 101 | Interactively split up <commit> into two commits by choosing |
| 102 | hunks introduced by it that will be moved into the new split-out |
| 103 | commit. These hunks will then be written into a new commit that |
| 104 | becomes the parent of the previous commit. The original commit |
| 105 | stays intact, except that its parent will be the newly split-out |
| 106 | commit. |
| 107 | + |
| 108 | The commit messages of the split-up commits will be asked for by launching |
| 109 | the configured editor. Authorship of the commit will be the same as for the |
| 110 | original commit. |
| 111 | + |
| 112 | If passed, _<pathspec>_ can be used to limit which changes shall be split out |
| 113 | of the original commit. Files not matching any of the pathspecs will remain |
| 114 | part of the original commit. For more details, see the 'pathspec' entry in |
| 115 | linkgit:gitglossary[7]. |
| 116 | + |
| 117 | It is invalid to select either all or no hunks, as that would lead to |
| 118 | one of the commits becoming empty. |
| 119 | |
| 120 | `squash <revision-range>`:: |
| 121 | Fold all commits in _<revision-range>_ into the oldest commit of that |
| 122 | range. The resulting commit keeps the oldest commit's authorship and |
| 123 | takes the tree of the range's newest commit, so the whole range |
| 124 | collapses into a single commit. Commits above the range are replayed |
| 125 | on top of the result. |
| 126 | + |
| 127 | The range is given in the usual `<base>..<tip>` form, where _<base>_ is |
| 128 | the commit just below the oldest commit to squash. For example, `git |
| 129 | history squash HEAD~3..HEAD` folds the three most recent commits into |
| 130 | one, and `git history squash HEAD~5..HEAD~2` squashes an interior range |
| 131 | while leaving the two newest commits in place. Several revisions may be |
| 132 | given, for example `HEAD~3..HEAD ^topic` to additionally exclude what is |
| 133 | already on `topic`. Rev-list options may also be given, but any that would |
| 134 | change how the range is walked are overridden with a warning. |
| 135 | + |
| 136 | The oldest commit's message is preserved by default, except that an `amend!` |
| 137 | commit targeting it replaces its message. With `--reedit-message`, an editor |
| 138 | opens pre-filled with the messages of all the folded commits so you can |
| 139 | combine them. A merge commit inside the range is folded like any other, but |
| 140 | the range must have a single base, so a range that reaches more than one entry |
| 141 | point (for example a side branch that forked before the range and was later |
| 142 | merged into it) is rejected. |
| 143 | + |
| 144 | A `fixup!`, `squash!`, or `amend!` commit is refused unless the commit it |
| 145 | targets is also in the range, so the fold does not silently absorb a |
| 146 | marker meant for a commit outside it. As an exception, a range made up entirely |
| 147 | of markers for one target is combined into a single commit, keeping the last |
| 148 | `amend!` message if there is one. |
| 149 | + |
| 150 | With `--reedit-message` the template mirrors `git rebase -i --autosquash`: |
| 151 | each `fixup!`, `squash!`, or `amend!` is grouped under the commit it |
| 152 | targets rather than shown in commit order. A `fixup!` message is dropped |
| 153 | (commented out in full), a `squash!` keeps its body with only the marker |
| 154 | subject commented, and an `amend!` replaces its target's message, unless |
| 155 | a `squash!` folded into that target first, in which case it keeps its |
| 156 | body like a `squash!`. |
| 157 | + |
| 158 | A branch or tag that points at a commit inside the range would be left |
| 159 | dangling once those commits are folded away, so with the default |
| 160 | `--update-refs=branches` the command refuses. Rerun with |
| 161 | `--update-refs=head` to rewrite only the current branch and leave such |
| 162 | refs pointing at the old commits. |
| 163 | |
| 164 | OPTIONS |
| 165 | ------- |
| 166 | |
| 167 | `--dry-run`:: |
| 168 | Do not update any references, but instead print any ref updates in a |
| 169 | format that can be consumed by linkgit:git-update-ref[1]. Necessary new |
| 170 | objects will be written into the repository, so applying these printed |
| 171 | ref updates is generally safe. |
| 172 | |
| 173 | `--reedit-message`:: |
| 174 | Open an editor to modify the rewritten commit's message. For `squash` |
| 175 | the editor is pre-filled with the messages of all the folded commits. |
| 176 | |
| 177 | `--empty=(drop|keep|abort)`:: |
| 178 | Control what happens when a commit becomes empty as a result of the |
| 179 | fixup. This can happen in two situations: |
| 180 | + |
| 181 | -- |
| 182 | * The fixup target itself becomes empty because the staged changes exactly |
| 183 | cancel out all changes introduced by that commit. |
| 184 | |
| 185 | * A descendant commit becomes empty during replay because it introduced the |
| 186 | same change that was just fixed up into an ancestor. |
| 187 | -- |
| 188 | + |
| 189 | With `drop` (the default), empty commits are removed from the rewritten |
| 190 | history. Descendants of a dropped target commit are replayed directly onto |
| 191 | the target's parent. Note that dropping the root commit is not supported; |
| 192 | see LIMITATIONS. |
| 193 | + |
| 194 | With `keep`, empty commits are retained in the rewritten history as-is. |
| 195 | + |
| 196 | With `abort`, the command stops with an error if any commit would become |
| 197 | empty. |
| 198 | |
| 199 | `--update-refs=(branches|head)`:: |
| 200 | Control which references will be updated by the command, if any. With |
| 201 | `branches`, all local branches that point to commits which are |
| 202 | descendants of the original commit will be rewritten. With `head`, only |
| 203 | the current `HEAD` reference will be rewritten. Defaults to `branches`. |
| 204 | |
| 205 | EXAMPLES |
| 206 | -------- |
| 207 | |
| 208 | Fixup a commit |
| 209 | ~~~~~~~~~~~~~~ |
| 210 | |
| 211 | ---------- |
| 212 | $ git log --oneline --stat |
| 213 | abc1234 (HEAD -> main) third |
| 214 | third.txt | 1 + |
| 215 | def5678 second |
| 216 | second.txt | 1 + |
| 217 | ghi9012 first |
| 218 | first.txt | 1 + |
| 219 | |
| 220 | $ echo "change" >>unrelated.txt |
| 221 | $ git add unrelated.txt |
| 222 | $ git history fixup ghi9012 |
| 223 | |
| 224 | $ git log --oneline --stat |
| 225 | jkl3456 (HEAD -> main) third |
| 226 | third.txt | 1 + |
| 227 | mno7890 second |
| 228 | second.txt | 1 + |
| 229 | pqr1234 first |
| 230 | first.txt | 1 + |
| 231 | unrelated.txt | 1 + |
| 232 | ---------- |
| 233 | |
| 234 | The staged addition of `unrelated.txt` has been incorporated into the `first` |
| 235 | commit. All descendant commits have been replayed on top of the rewritten |
| 236 | history. |
| 237 | |
| 238 | Drop a commit |
| 239 | ~~~~~~~~~~~~~ |
| 240 | |
| 241 | ---------- |
| 242 | $ git log --oneline |
| 243 | abc1234 (HEAD -> main) third |
| 244 | def5678 second |
| 245 | ghi9012 first |
| 246 | |
| 247 | $ git history drop 'main^{/second}' |
| 248 | |
| 249 | $ git log --oneline |
| 250 | jkl3456 (HEAD -> main) third |
| 251 | ghi9012 first |
| 252 | ---------- |
| 253 | |
| 254 | The `second` commit has been removed from the history, and `third` has been |
| 255 | replayed directly on top of `first`. All branches that pointed at the dropped |
| 256 | commit have been moved to its parent. |
| 257 | |
| 258 | Split a commit |
| 259 | ~~~~~~~~~~~~~~ |
| 260 | |
| 261 | ---------- |
| 262 | $ git log --stat --oneline |
| 263 | 3f81232 (HEAD -> main) original |
| 264 | bar | 1 + |
| 265 | foo | 1 + |
| 266 | 2 files changed, 2 insertions(+) |
| 267 | |
| 268 | $ git history split HEAD |
| 269 | diff --git a/bar b/bar |
| 270 | new file mode 100644 |
| 271 | index 0000000..5716ca5 |
| 272 | --- /dev/null |
| 273 | +++ b/bar |
| 274 | @@ -0,0 +1 @@ |
| 275 | +bar |
| 276 | (1/1) Stage addition [y,n,q,a,d,p,?]? y |
| 277 | |
| 278 | diff --git a/foo b/foo |
| 279 | new file mode 100644 |
| 280 | index 0000000..257cc56 |
| 281 | --- /dev/null |
| 282 | +++ b/foo |
| 283 | @@ -0,0 +1 @@ |
| 284 | +foo |
| 285 | (1/1) Stage addition [y,n,q,a,d,p,?]? n |
| 286 | |
| 287 | $ git log --stat --oneline |
| 288 | 7cebe64 (HEAD -> main) original |
| 289 | foo | 1 + |
| 290 | 1 file changed, 1 insertion(+) |
| 291 | d1582f3 split-out commit |
| 292 | bar | 1 + |
| 293 | 1 file changed, 1 insertion(+) |
| 294 | ---------- |
| 295 | |
| 296 | GIT |
| 297 | --- |
| 298 | Part of the linkgit:git[1] suite |