diff options
Diffstat (limited to 'third_party/git/Documentation/git-rerere.txt')
| -rw-r--r-- | third_party/git/Documentation/git-rerere.txt | 222 |
1 files changed, 0 insertions, 222 deletions
diff --git a/third_party/git/Documentation/git-rerere.txt b/third_party/git/Documentation/git-rerere.txt deleted file mode 100644 index 4cfc88337808..000000000000 --- a/third_party/git/Documentation/git-rerere.txt +++ /dev/null @@ -1,222 +0,0 @@ -git-rerere(1) -============= - -NAME ----- -git-rerere - Reuse recorded resolution of conflicted merges - -SYNOPSIS --------- -[verse] -'git rerere' ['clear'|'forget' <pathspec>|'diff'|'remaining'|'status'|'gc'] - -DESCRIPTION ------------ - -In a workflow employing relatively long lived topic branches, -the developer sometimes needs to resolve the same conflicts over -and over again until the topic branches are done (either merged -to the "release" branch, or sent out and accepted upstream). - -This command assists the developer in this process by recording -conflicted automerge results and corresponding hand resolve results -on the initial manual merge, and applying previously recorded -hand resolutions to their corresponding automerge results. - -[NOTE] -You need to set the configuration variable `rerere.enabled` in order to -enable this command. - - -COMMANDS --------- - -Normally, 'git rerere' is run without arguments or user-intervention. -However, it has several commands that allow it to interact with -its working state. - -'clear':: - -Reset the metadata used by rerere if a merge resolution is to be -aborted. Calling 'git am [--skip|--abort]' or 'git rebase [--skip|--abort]' -will automatically invoke this command. - -'forget' <pathspec>:: - -Reset the conflict resolutions which rerere has recorded for the current -conflict in <pathspec>. - -'diff':: - -Display diffs for the current state of the resolution. It is -useful for tracking what has changed while the user is resolving -conflicts. Additional arguments are passed directly to the system -'diff' command installed in PATH. - -'status':: - -Print paths with conflicts whose merge resolution rerere will record. - -'remaining':: - -Print paths with conflicts that have not been autoresolved by rerere. -This includes paths whose resolutions cannot be tracked by rerere, -such as conflicting submodules. - -'gc':: - -Prune records of conflicted merges that -occurred a long time ago. By default, unresolved conflicts older -than 15 days and resolved conflicts older than 60 -days are pruned. These defaults are controlled via the -`gc.rerereUnresolved` and `gc.rerereResolved` configuration -variables respectively. - - -DISCUSSION ----------- - -When your topic branch modifies an overlapping area that your -master branch (or upstream) touched since your topic branch -forked from it, you may want to test it with the latest master, -even before your topic branch is ready to be pushed upstream: - ------------- - o---*---o topic - / - o---o---o---*---o---o master ------------- - -For such a test, you need to merge master and topic somehow. -One way to do it is to pull master into the topic branch: - ------------- - $ git switch topic - $ git merge master - - o---*---o---+ topic - / / - o---o---o---*---o---o master ------------- - -The commits marked with `*` touch the same area in the same -file; you need to resolve the conflicts when creating the commit -marked with `+`. Then you can test the result to make sure your -work-in-progress still works with what is in the latest master. - -After this test merge, there are two ways to continue your work -on the topic. The easiest is to build on top of the test merge -commit `+`, and when your work in the topic branch is finally -ready, pull the topic branch into master, and/or ask the -upstream to pull from you. By that time, however, the master or -the upstream might have been advanced since the test merge `+`, -in which case the final commit graph would look like this: - ------------- - $ git switch topic - $ git merge master - $ ... work on both topic and master branches - $ git switch master - $ git merge topic - - o---*---o---+---o---o topic - / / \ - o---o---o---*---o---o---o---o---+ master ------------- - -When your topic branch is long-lived, however, your topic branch -would end up having many such "Merge from master" commits on it, -which would unnecessarily clutter the development history. -Readers of the Linux kernel mailing list may remember that Linus -complained about such too frequent test merges when a subsystem -maintainer asked to pull from a branch full of "useless merges". - -As an alternative, to keep the topic branch clean of test -merges, you could blow away the test merge, and keep building on -top of the tip before the test merge: - ------------- - $ git switch topic - $ git merge master - $ git reset --hard HEAD^ ;# rewind the test merge - $ ... work on both topic and master branches - $ git switch master - $ git merge topic - - o---*---o-------o---o topic - / \ - o---o---o---*---o---o---o---o---+ master ------------- - -This would leave only one merge commit when your topic branch is -finally ready and merged into the master branch. This merge -would require you to resolve the conflict, introduced by the -commits marked with `*`. However, this conflict is often the -same conflict you resolved when you created the test merge you -blew away. 'git rerere' helps you resolve this final -conflicted merge using the information from your earlier hand -resolve. - -Running the 'git rerere' command immediately after a conflicted -automerge records the conflicted working tree files, with the -usual conflict markers `<<<<<<<`, `=======`, and `>>>>>>>` in -them. Later, after you are done resolving the conflicts, -running 'git rerere' again will record the resolved state of these -files. Suppose you did this when you created the test merge of -master into the topic branch. - -Next time, after seeing the same conflicted automerge, -running 'git rerere' will perform a three-way merge between the -earlier conflicted automerge, the earlier manual resolution, and -the current conflicted automerge. -If this three-way merge resolves cleanly, the result is written -out to your working tree file, so you do not have to manually -resolve it. Note that 'git rerere' leaves the index file alone, -so you still need to do the final sanity checks with `git diff` -(or `git diff -c`) and 'git add' when you are satisfied. - -As a convenience measure, 'git merge' automatically invokes -'git rerere' upon exiting with a failed automerge and 'git rerere' -records the hand resolve when it is a new conflict, or reuses the earlier hand -resolve when it is not. 'git commit' also invokes 'git rerere' -when committing a merge result. What this means is that you do -not have to do anything special yourself (besides enabling -the rerere.enabled config variable). - -In our example, when you do the test merge, the manual -resolution is recorded, and it will be reused when you do the -actual merge later with the updated master and topic branch, as long -as the recorded resolution is still applicable. - -The information 'git rerere' records is also used when running -'git rebase'. After blowing away the test merge and continuing -development on the topic branch: - ------------- - o---*---o-------o---o topic - / - o---o---o---*---o---o---o---o master - - $ git rebase master topic - - o---*---o-------o---o topic - / - o---o---o---*---o---o---o---o master ------------- - -you could run `git rebase master topic`, to bring yourself -up to date before your topic is ready to be sent upstream. -This would result in falling back to a three-way merge, and it -would conflict the same way as the test merge you resolved earlier. -'git rerere' will be run by 'git rebase' to help you resolve this -conflict. - -[NOTE] 'git rerere' relies on the conflict markers in the file to -detect the conflict. If the file already contains lines that look the -same as lines with conflict markers, 'git rerere' may fail to record a -conflict resolution. To work around this, the `conflict-marker-size` -setting in linkgit:gitattributes[5] can be used. - -GIT ---- -Part of the linkgit:git[1] suite |