From 1b593e1ea4d2af0f6444d9a7788d5d99abd6fde5 Mon Sep 17 00:00:00 2001 From: Vincent Ambo Date: Sat, 11 Jan 2020 23:36:56 +0000 Subject: Squashed 'third_party/git/' content from commit cb71568594 git-subtree-dir: third_party/git git-subtree-split: cb715685942260375e1eb8153b0768a376e4ece7 --- Documentation/git-rebase.txt | 1053 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1053 insertions(+) create mode 100644 Documentation/git-rebase.txt (limited to 'Documentation/git-rebase.txt') diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt new file mode 100644 index 000000000000..6156609cf714 --- /dev/null +++ b/Documentation/git-rebase.txt @@ -0,0 +1,1053 @@ +git-rebase(1) +============= + +NAME +---- +git-rebase - Reapply commits on top of another base tip + +SYNOPSIS +-------- +[verse] +'git rebase' [-i | --interactive] [] [--exec ] [--onto ] + [ []] +'git rebase' [-i | --interactive] [] [--exec ] [--onto ] + --root [] +'git rebase' (--continue | --skip | --abort | --quit | --edit-todo | --show-current-patch) + +DESCRIPTION +----------- +If is specified, 'git rebase' will perform an automatic +`git switch ` before doing anything else. Otherwise +it remains on the current branch. + +If is not specified, the upstream configured in +branch..remote and branch..merge options will be used (see +linkgit:git-config[1] for details) and the `--fork-point` option is +assumed. If you are currently not on any branch or if the current +branch does not have a configured upstream, the rebase will abort. + +All changes made by commits in the current branch but that are not +in are saved to a temporary area. This is the same set +of commits that would be shown by `git log ..HEAD`; or by +`git log 'fork_point'..HEAD`, if `--fork-point` is active (see the +description on `--fork-point` below); or by `git log HEAD`, if the +`--root` option is specified. + +The current branch is reset to , or if the +--onto option was supplied. This has the exact same effect as +`git reset --hard ` (or ). ORIG_HEAD is set +to point at the tip of the branch before the reset. + +The commits that were previously saved into the temporary area are +then reapplied to the current branch, one by one, in order. Note that +any commits in HEAD which introduce the same textual changes as a commit +in HEAD.. are omitted (i.e., a patch already accepted upstream +with a different commit message or timestamp will be skipped). + +It is possible that a merge failure will prevent this process from being +completely automatic. You will have to resolve any such merge failure +and run `git rebase --continue`. Another option is to bypass the commit +that caused the merge failure with `git rebase --skip`. To check out the +original and remove the .git/rebase-apply working files, use the +command `git rebase --abort` instead. + +Assume the following history exists and the current branch is "topic": + +------------ + A---B---C topic + / + D---E---F---G master +------------ + +From this point, the result of either of the following commands: + + + git rebase master + git rebase master topic + +would be: + +------------ + A'--B'--C' topic + / + D---E---F---G master +------------ + +*NOTE:* The latter form is just a short-hand of `git checkout topic` +followed by `git rebase master`. When rebase exits `topic` will +remain the checked-out branch. + +If the upstream branch already contains a change you have made (e.g., +because you mailed a patch which was applied upstream), then that commit +will be skipped. For example, running `git rebase master` on the +following history (in which `A'` and `A` introduce the same set of changes, +but have different committer information): + +------------ + A---B---C topic + / + D---E---A'---F master +------------ + +will result in: + +------------ + B'---C' topic + / + D---E---A'---F master +------------ + +Here is how you would transplant a topic branch based on one +branch to another, to pretend that you forked the topic branch +from the latter branch, using `rebase --onto`. + +First let's assume your 'topic' is based on branch 'next'. +For example, a feature developed in 'topic' depends on some +functionality which is found in 'next'. + +------------ + o---o---o---o---o master + \ + o---o---o---o---o next + \ + o---o---o topic +------------ + +We want to make 'topic' forked from branch 'master'; for example, +because the functionality on which 'topic' depends was merged into the +more stable 'master' branch. We want our tree to look like this: + +------------ + o---o---o---o---o master + | \ + | o'--o'--o' topic + \ + o---o---o---o---o next +------------ + +We can get this using the following command: + + git rebase --onto master next topic + + +Another example of --onto option is to rebase part of a +branch. If we have the following situation: + +------------ + H---I---J topicB + / + E---F---G topicA + / + A---B---C---D master +------------ + +then the command + + git rebase --onto master topicA topicB + +would result in: + +------------ + H'--I'--J' topicB + / + | E---F---G topicA + |/ + A---B---C---D master +------------ + +This is useful when topicB does not depend on topicA. + +A range of commits could also be removed with rebase. If we have +the following situation: + +------------ + E---F---G---H---I---J topicA +------------ + +then the command + + git rebase --onto topicA~5 topicA~3 topicA + +would result in the removal of commits F and G: + +------------ + E---H'---I'---J' topicA +------------ + +This is useful if F and G were flawed in some way, or should not be +part of topicA. Note that the argument to --onto and the +parameter can be any valid commit-ish. + +In case of conflict, 'git rebase' will stop at the first problematic commit +and leave conflict markers in the tree. You can use 'git diff' to locate +the markers (<<<<<<) and make edits to resolve the conflict. For each +file you edit, you need to tell Git that the conflict has been resolved, +typically this would be done with + + + git add + + +After resolving the conflict manually and updating the index with the +desired resolution, you can continue the rebasing process with + + + git rebase --continue + + +Alternatively, you can undo the 'git rebase' with + + + git rebase --abort + +CONFIGURATION +------------- + +include::config/rebase.txt[] + +OPTIONS +------- +--onto :: + Starting point at which to create the new commits. If the + --onto option is not specified, the starting point is + . May be any valid commit, and not just an + existing branch name. ++ +As a special case, you may use "A\...B" as a shortcut for the +merge base of A and B if there is exactly one merge base. You can +leave out at most one of A and B, in which case it defaults to HEAD. + +:: + Upstream branch to compare against. May be any valid commit, + not just an existing branch name. Defaults to the configured + upstream for the current branch. + +:: + Working branch; defaults to HEAD. + +--continue:: + Restart the rebasing process after having resolved a merge conflict. + +--abort:: + Abort the rebase operation and reset HEAD to the original + branch. If was provided when the rebase operation was + started, then HEAD will be reset to . Otherwise HEAD + will be reset to where it was when the rebase operation was + started. + +--quit:: + Abort the rebase operation but HEAD is not reset back to the + original branch. The index and working tree are also left + unchanged as a result. + +--keep-empty:: + Keep the commits that do not change anything from its + parents in the result. ++ +See also INCOMPATIBLE OPTIONS below. + +--allow-empty-message:: + By default, rebasing commits with an empty message will fail. + This option overrides that behavior, allowing commits with empty + messages to be rebased. ++ +See also INCOMPATIBLE OPTIONS below. + +--skip:: + Restart the rebasing process by skipping the current patch. + +--edit-todo:: + Edit the todo list during an interactive rebase. + +--show-current-patch:: + Show the current patch in an interactive rebase or when rebase + is stopped because of conflicts. This is the equivalent of + `git show REBASE_HEAD`. + +-m:: +--merge:: + Use merging strategies to rebase. When the recursive (default) merge + strategy is used, this allows rebase to be aware of renames on the + upstream side. ++ +Note that a rebase merge works by replaying each commit from the working +branch on top of the branch. Because of this, when a merge +conflict happens, the side reported as 'ours' is the so-far rebased +series, starting with , and 'theirs' is the working branch. In +other words, the sides are swapped. ++ +See also INCOMPATIBLE OPTIONS below. + +-s :: +--strategy=:: + Use the given merge strategy. + If there is no `-s` option 'git merge-recursive' is used + instead. This implies --merge. ++ +Because 'git rebase' replays each commit from the working branch +on top of the branch using the given strategy, using +the 'ours' strategy simply empties all patches from the , +which makes little sense. ++ +See also INCOMPATIBLE OPTIONS below. + +-X :: +--strategy-option=:: + Pass the through to the merge strategy. + This implies `--merge` and, if no strategy has been + specified, `-s recursive`. Note the reversal of 'ours' and + 'theirs' as noted above for the `-m` option. ++ +See also INCOMPATIBLE OPTIONS below. + +--rerere-autoupdate:: +--no-rerere-autoupdate:: + Allow the rerere mechanism to update the index with the + result of auto-conflict resolution if possible. + +-S[]:: +--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. + +-q:: +--quiet:: + Be quiet. Implies --no-stat. + +-v:: +--verbose:: + Be verbose. Implies --stat. + +--stat:: + Show a diffstat of what changed upstream since the last rebase. The + diffstat is also controlled by the configuration option rebase.stat. + +-n:: +--no-stat:: + Do not show a diffstat as part of the rebase process. + +--no-verify:: + This option bypasses the pre-rebase hook. See also linkgit:githooks[5]. + +--verify:: + Allows the pre-rebase hook to run, which is the default. This option can + be used to override --no-verify. See also linkgit:githooks[5]. + +-C:: + Ensure at least lines of surrounding context match before + and after each change. When fewer lines of surrounding + context exist they all must match. By default no context is + ever ignored. ++ +See also INCOMPATIBLE OPTIONS below. + +--no-ff:: +--force-rebase:: +-f:: + Individually replay all rebased commits instead of fast-forwarding + over the unchanged ones. This ensures that the entire history of + the rebased branch is composed of new commits. ++ +You may find this helpful after reverting a topic branch merge, as this option +recreates the topic branch with fresh commits so it can be remerged +successfully without needing to "revert the reversion" (see the +link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for +details). + +--fork-point:: +--no-fork-point:: + Use reflog to find a better common ancestor between + and when calculating which commits have been + introduced by . ++ +When --fork-point is active, 'fork_point' will be used instead of + to calculate the set of commits to rebase, where +'fork_point' is the result of `git merge-base --fork-point +` command (see linkgit:git-merge-base[1]). If 'fork_point' +ends up being empty, the will be used as a fallback. ++ +If either or --root is given on the command line, then the +default is `--no-fork-point`, otherwise the default is `--fork-point`. + +--ignore-whitespace:: +--whitespace=