diff options
Diffstat (limited to 'Documentation/git-rebase.txt')
| -rw-r--r-- | Documentation/git-rebase.txt | 150 |
1 files changed, 116 insertions, 34 deletions
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 504945c691..47984e84ed 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -8,11 +8,11 @@ git-rebase - Forward-port local commits to the updated upstream head SYNOPSIS -------- [verse] -'git rebase' [-i | --interactive] [options] [--onto <newbase>] - [<upstream>] [<branch>] -'git rebase' [-i | --interactive] [options] --onto <newbase> +'git rebase' [-i | --interactive] [options] [--exec <cmd>] [--onto <newbase>] + [<upstream> [<branch>]] +'git rebase' [-i | --interactive] [options] [--exec <cmd>] [--onto <newbase>] --root [<branch>] -'git rebase' --continue | --skip | --abort +'git rebase' --continue | --skip | --abort | --edit-todo DESCRIPTION ----------- @@ -21,15 +21,17 @@ If <branch> is specified, 'git rebase' will perform an automatic it remains on the current branch. If <upstream> is not specified, the upstream configured in -branch.<name>.remote and branch.<name>.merge options will be used; see -linkgit:git-config[1] for details. If you are currently not on any -branch or if the current branch does not have a configured upstream, -the rebase will abort. +branch.<name>.remote and branch.<name>.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 <upstream> are saved to a temporary area. This is the same set -of commits that would be shown by `git log <upstream>..HEAD` (or -`git log HEAD`, if --root is specified). +of commits that would be shown by `git log <upstream>..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 <upstream>, or <newbase> if the --onto option was supplied. This has the exact same effect as @@ -179,7 +181,7 @@ 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, +file you edit, you need to tell Git that the conflict has been resolved, typically this would be done with @@ -205,12 +207,15 @@ rebase.stat:: Whether to show a diffstat of what changed upstream since the last rebase. False by default. -rebase.autosquash:: +rebase.autoSquash:: If set to true enable '--autosquash' option by default. +rebase.autoStash:: + If set to true enable '--autostash' option by default. + OPTIONS ------- -<newbase>:: +--onto <newbase>:: Starting point at which to create the new commits. If the --onto option is not specified, the starting point is <upstream>. May be any valid commit, and not just an @@ -238,9 +243,16 @@ leave out at most one of A and B, in which case it defaults to HEAD. will be reset to where it was when the rebase operation was started. +--keep-empty:: + Keep the commits that do not change anything from its + parents in the result. + --skip:: Restart the rebasing process by skipping the current patch. +--edit-todo:: + Edit the todo list during an interactive rebase. + -m:: --merge:: Use merging strategies to rebase. When the recursive (default) merge @@ -267,9 +279,13 @@ which makes little sense. -X <strategy-option>:: --strategy-option=<strategy-option>:: Pass the <strategy-option> through to the merge strategy. - This implies `\--merge` and, if no strategy has been + This implies `--merge` and, if no strategy has been specified, `-s recursive`. Note the reversal of 'ours' and - 'theirs' as noted in above for the `-m` option. + 'theirs' as noted above for the `-m` option. + +-S[<keyid>]:: +--gpg-sign[=<keyid>]:: + GPG-sign commits. -q:: --quiet:: @@ -302,17 +318,29 @@ which makes little sense. -f:: --force-rebase:: - Force the rebase even if the current branch is a descendant - of the commit you are rebasing onto. Normally non-interactive rebase will - exit with the message "Current branch is up to date" in such a - situation. - Incompatible with the --interactive option. + Force a rebase even if the current branch is up-to-date and + the command without `--force` would return without doing anything. + You may find this (or --no-ff with an interactive rebase) 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.txt[revert-a-faulty-merge How-To] for details). +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 <upstream> + and <branch> when calculating which commits have been + introduced by <branch>. ++ +When --fork-point is active, 'fork_point' will be used instead of +<upstream> to calculate the set of commits to rebase, where +'fork_point' is the result of `git merge-base --fork-point <upstream> +<branch>` command (see linkgit:git-merge-base[1]). If 'fork_point' +ends up being empty, the <upstream> will be used as a fallback. ++ +If either <upstream> or --root is given on the command line, then the +default is `--no-fork-point`, otherwise the default is `--fork-point`. --ignore-whitespace:: --whitespace=<option>:: @@ -334,20 +362,44 @@ link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for details). -p:: --preserve-merges:: - Instead of ignoring merges, try to recreate them. + Recreate merge commits instead of flattening the history by replaying + commits a merge commit introduces. Merge conflict resolutions or manual + amendments to merge commits are not preserved. + This uses the `--interactive` machinery internally, but combining it with the `--interactive` option explicitly is generally not a good idea unless you know what you are doing (see BUGS below). +-x <cmd>:: +--exec <cmd>:: + Append "exec <cmd>" after each line creating a commit in the + final history. <cmd> will be interpreted as one or more shell + commands. ++ +This option can only be used with the `--interactive` option +(see INTERACTIVE MODE below). ++ +You may execute several commands by either using one instance of `--exec` +with several commands: ++ + git rebase -i --exec "cmd1 && cmd2 && ..." ++ +or by giving more than one `--exec`: ++ + git rebase -i --exec "cmd1" --exec "cmd2" --exec ... ++ +If `--autosquash` is used, "exec" lines will not be appended for +the intermediate commits, and will only appear at the end of each +squash/fixup series. --root:: Rebase all commits reachable from <branch>, instead of limiting them with an <upstream>. This allows you to rebase - the root commit(s) on a branch. Must be used with --onto, and + the root commit(s) on a branch. When used with --onto, it will skip changes already contained in <newbase> (instead of - <upstream>). When used together with --preserve-merges, 'all' - root commits will be rewritten to have <newbase> as parent + <upstream>) whereas without --onto it will operate on every change. + When used together with both --onto and --preserve-merges, + 'all' root commits will be rewritten to have <newbase> as parent instead. --autosquash:: @@ -357,14 +409,23 @@ idea unless you know what you are doing (see BUGS below). the same ..., automatically modify the todo list of rebase -i so that the commit marked for squashing comes right after the commit to be modified, and change the action of the moved - commit from `pick` to `squash` (or `fixup`). + commit from `pick` to `squash` (or `fixup`). Ignores subsequent + "fixup! " or "squash! " after the first, in case you referred to an + earlier fixup/squash with `git commit --fixup/--squash`. + This option is only valid when the '--interactive' option is used. + If the '--autosquash' option is enabled by default using the -configuration variable `rebase.autosquash`, this option can be +configuration variable `rebase.autoSquash`, this option can be used to override and disable this setting. +--[no-]autostash:: + Automatically create a temporary stash before the operation + begins, and apply it after the operation ends. This means + that you can run rebase on a dirty worktree. However, use + with care: the final stash application after a successful + rebase might result in non-trivial conflicts. + --no-ff:: With --interactive, cherry-pick all rebased commits instead of fast-forwarding over the unchanged ones. This ensures that the @@ -375,7 +436,7 @@ Without --interactive, this is a synonym for --force-rebase. 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.txt[revert-a-faulty-merge How-To] for details). +link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details). include::merge-strategies.txt[] @@ -409,10 +470,13 @@ The interactive mode is meant for this type of workflow: where point 2. consists of several instances of -a. regular use +a) regular use + 1. finish something worthy of a commit 2. commit -b. independent fixup + +b) independent fixup + 1. realize that something does not work 2. fix that 3. commit it @@ -514,6 +578,24 @@ in `$SHELL`, or the default shell if `$SHELL` is not set), so you can use shell features (like "cd", ">", ";" ...). The command is run from the root of the working tree. +---------------------------------- +$ git rebase -i --exec "make test" +---------------------------------- + +This command lets you check that intermediate commits are compilable. +The todo list becomes like that: + +-------------------- +pick 5928aea one +exec make test +pick 04d0fda two +exec make test +pick ba46169 three +exec make test +pick f4593f9 four +exec make test +-------------------- + SPLITTING COMMITS ----------------- @@ -608,8 +690,8 @@ Easy case: The changes are literally the same.:: Hard case: The changes are not the same.:: This happens if the 'subsystem' rebase had conflicts, or used - `\--interactive` to omit, edit, squash, or fixup commits; or - if the upstream used one of `commit \--amend`, `reset`, or + `--interactive` to omit, edit, squash, or fixup commits; or + if the upstream used one of `commit --amend`, `reset`, or `filter-branch`. @@ -645,7 +727,7 @@ correspond to the ones before the rebase. NOTE: While an "easy case recovery" sometimes appears to be successful even in the hard case, it may have unintended consequences. For example, a commit that was removed via `git rebase - \--interactive` will be **resurrected**! + --interactive` will be **resurrected**! The idea is to manually tell 'git rebase' "where the old 'subsystem' ended and your 'topic' began", that is, what the old merge-base @@ -653,7 +735,7 @@ between them was. You will have to find a way to name the last commit of the old 'subsystem', for example: * With the 'subsystem' reflog: after 'git fetch', the old tip of - 'subsystem' is at `subsystem@\{1}`. Subsequent fetches will + 'subsystem' is at `subsystem@{1}`. Subsequent fetches will increase the number. (See linkgit:git-reflog[1].) * Relative to the tip of 'topic': knowing that your 'topic' has three |