summaryrefslogtreecommitdiff
path: root/Documentation/git-rebase.txt
AgeCommit message (Collapse)AuthorFilesLines
2019-07-09Merge branch 'nd/switch-and-restore'Libravatar Junio C Hamano1-1/+1
Two new commands "git switch" and "git restore" are introduced to split "checking out a branch to work on advancing its history" and "checking out paths out of the index and/or a tree-ish to work on advancing the current history" out of the single "git checkout" command. * nd/switch-and-restore: (46 commits) completion: disable dwim on "git switch -d" switch: allow to switch in the middle of bisect t2027: use test_must_be_empty Declare both git-switch and git-restore experimental help: move git-diff and git-reset to different groups doc: promote "git restore" user-manual.txt: prefer 'merge --abort' over 'reset --hard' completion: support restore t: add tests for restore restore: support --patch restore: replace --force with --ignore-unmerged restore: default to --source=HEAD when only --staged is specified restore: reject invalid combinations with --staged restore: add --worktree and --staged checkout: factor out worktree checkout code restore: disable overlay mode by default restore: make pathspec mandatory restore: take tree-ish from --source option instead checkout: split part of it to new command 'restore' doc: promote "git switch" ...
2019-07-09Merge branch 'pw/doc-synopsis-markup-opmode-options'Libravatar Junio C Hamano1-1/+1
Docfix. * pw/doc-synopsis-markup-opmode-options: show --continue/skip etc. consistently in synopsis
2019-06-17show --continue/skip etc. consistently in synopsisLibravatar Phillip Wood1-1/+1
Command mode options that the user can choose one among many are listed like this in the documentation: git am (--continue | --skip | --abort | --quit) They are listed on a single line and in parenthesis, because they are not optional. But documentation pages for some commands deviate from this norm. Fix the merge and rebase docs to match this style. Signed-off-by: Phillip Wood <phillip.wood@dunelm.org.uk> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-05-30Merge branch 'js/rebase-deprecate-preserve-merges'Libravatar Junio C Hamano1-2/+3
A bit more leftover clean-up to deprepcate "rebase -p". * js/rebase-deprecate-preserve-merges: rebase docs: recommend `-r` over `-p` docs: say that `--rebase=preserve` is deprecated tests: mark a couple more test cases as requiring `rebase -p`
2019-05-28rebase docs: recommend `-r` over `-p`Libravatar Johannes Schindelin1-2/+3
The `--preserve-merges` option is now deprecated in favor of `--rebase-merges`; Let's stop recommending the former. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-04-16Merge branch 'pw/rerere-autoupdate'Libravatar Junio C Hamano1-0/+5
Doc updates. * pw/rerere-autoupdate: merge: tweak --rerere-autoupdate documentation am/cherry-pick/rebase/revert: document --rerere-autoupdate
2019-04-10Merge branch 'js/rebase-deprecate-preserve-merges'Libravatar Junio C Hamano1-11/+12
"git rebase --rebase-merges" replaces its old "--preserve-merges" option; the latter is now marked as deprecated. * js/rebase-deprecate-preserve-merges: rebase: deprecate --preserve-merges
2019-04-02doc: promote "git switch"Libravatar Nguyễn Thái Ngọc Duy1-1/+1
The new command "git switch" is added to avoid the confusion of one-command-do-all "git checkout" for new users. They are also helpful to avoid ambiguation context. For these reasons, promote it everywhere possible. This includes documentation, suggestions/advice from other commands... The "Checking out files" progress line in unpack-trees.c is also updated to "Updating files" to be neutral to both git-checkout and git-switch. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-03-18am/cherry-pick/rebase/revert: document --rerere-autoupdateLibravatar Phillip Wood1-0/+5
This option was missing from the man pages of these commands. Signed-off-by: Phillip Wood <phillip.wood@dunelm.org.uk> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-03-12rebase: deprecate --preserve-mergesLibravatar Johannes Schindelin1-11/+12
We have something much better now: --rebase-merges (which is a complete re-design --preserve-merges, with a lot of issues fixed such as the inability to reorder commits with --preserve-merges). Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-03-11Merge branch 'js/rebase-recreate-merge'Libravatar Junio C Hamano1-1/+1
Docfix. * js/rebase-recreate-merge: rebase docs: fix "gitlink" typo
2019-03-01rebase docs: fix "gitlink" typoLibravatar Kyle Meyer1-1/+1
Change it to "linkgit" so that the reference is properly rendered. Signed-off-by: Kyle Meyer <kyle@kyleam.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-02-14Merge branch 'ea/rebase-compat-doc-fix'Libravatar Junio C Hamano1-1/+0
* ea/rebase-compat-doc-fix: docs/git-rebase: remove redundant entry in incompatible options list
2019-02-14Merge branch 'en/rebase-merge-on-sequencer'Libravatar Junio C Hamano1-2/+0
"git rebase --merge" as been reimplemented by reusing the internal machinery used for "git rebase -i". * en/rebase-merge-on-sequencer: git-rebase.txt: update to reflect merge now implemented on sequencer
2019-02-14git-rebase.txt: update to reflect merge now implemented on sequencerLibravatar Elijah Newren1-2/+0
Since commit 8fe9c3f21dff (Merge branch 'en/rebase-merge-on-sequencer', 2019-02-06), --merge now uses the interactive backend (and matches its behavior) so there is no separate merge backend anymore. Fix an oversight in the docs that should have been updated with the previous change. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-02-14docs/git-rebase: remove redundant entry in incompatible options listLibravatar Emilio Cobos Álvarez1-1/+0
The --autosquash option is implied by the earlier --[no-]autosquash entry in the list. Signed-off-by: Emilio Cobos Álvarez <emilio@crisal.io> Reviewed-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-02-08Merge branch 'js/rebase-i-redo-exec-fix'Libravatar Junio C Hamano1-6/+0
For "rebase -i --reschedule-failed-exec", we do not want the "-y" shortcut after all. * js/rebase-i-redo-exec-fix: Revert "rebase: introduce a shortcut for --reschedule-failed-exec"
2019-02-06Merge branch 'en/rebase-merge-on-sequencer'Libravatar Junio C Hamano1-14/+3
"git rebase --merge" as been reimplemented by reusing the internal machinery used for "git rebase -i". * en/rebase-merge-on-sequencer: rebase: implement --merge via the interactive machinery rebase: define linearization ordering and enforce it git-legacy-rebase: simplify unnecessary triply-nested if git-rebase, sequencer: extend --quiet option for the interactive machinery am, rebase--merge: do not overlook --skip'ed commits with post-rewrite t5407: add a test demonstrating how interactive handles --skip differently rebase: fix incompatible options error message rebase: make builtin and legacy script error messages the same
2019-02-06Revert "rebase: introduce a shortcut for --reschedule-failed-exec"Libravatar Johannes Schindelin1-6/+0
This patch was contributed only as a tentative "we could introduce a convenient short option if we do not want to change the default behavior in the long run" patch, opening the discussion whether other people agree with deprecating the current behavior in favor of the rescheduling behavior. But the consensus on the Git mailing list was that it would make sense to show a warning in the near future, and flip the default rebase.rescheduleFailedExec to reschedule failed `exec` commands by default. See e.g. <CAGZ79kZL5CRqCDRb6B-EedUm8Z_i4JuSF2=UtwwdRXMitrrOBw@mail.gmail.com> So let's back out that patch that added the `-y` short option that we agreed was not necessary or desirable. This reverts commit 81ef8ee75d5f348d3c71ff633d13d302124e1a5e. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-01-29Merge branch 'js/rebase-i-redo-exec'Libravatar Junio C Hamano1-0/+11
"git rebase -i" learned to re-execute a command given with 'exec' to run after it failed the last time. * js/rebase-i-redo-exec: rebase: introduce a shortcut for --reschedule-failed-exec rebase: add a config option to default to --reschedule-failed-exec rebase: introduce --reschedule-failed-exec
2019-01-14Merge branch 'en/directory-renames-nothanks-doc-update'Libravatar Junio C Hamano1-2/+3
Doc update. * en/directory-renames-nothanks-doc-update: git-rebase.txt: update note about directory rename detection and am
2019-01-14Merge branch 'km/rebase-doc-typofix'Libravatar Junio C Hamano1-1/+1
Doc update. * km/rebase-doc-typofix: rebase docs: drop stray word in merge command description
2019-01-07rebase: implement --merge via the interactive machineryLibravatar Elijah Newren1-14/+3
As part of an ongoing effort to make rebase have more uniform behavior, modify the merge backend to behave like the interactive one, by re-implementing it on top of the latter. Interactive rebases are implemented in terms of cherry-pick rather than the merge-recursive builtin, but cherry-pick also calls into the recursive merge machinery by default and can accept special merge strategies and/or special strategy options. As such, there really is not any need for having both git-rebase--merge and git-rebase--interactive anymore. Delete git-rebase--merge.sh and instead implement it in builtin/rebase.c. This results in a few deliberate but small user-visible changes: * The progress output is modified (see t3406 and t3420 for examples) * A few known test failures are now fixed (see t3421) * bash-prompt during a rebase --merge is now REBASE-i instead of REBASE-m. Reason: The prompt is a reflection of the backend in use; this allows users to report an issue to the git mailing list with the appropriate backend information, and allows advanced users to know where to search for relevant control files. (see t9903) testcase modification notes: t3406: --interactive and --merge had slightly different progress output while running; adjust a test to match the new expectation t3420: these test precise output while running, but rebase--am, rebase--merge, and rebase--interactive all were built on very different commands (am, merge-recursive, cherry-pick), so the tests expected different output for each type. Now we expect --merge and --interactive to have the same output. t3421: --interactive fixes some bugs in --merge! Wahoo! t9903: --merge uses the interactive backend so the prompt expected is now REBASE-i. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-12-11rebase: introduce a shortcut for --reschedule-failed-execLibravatar Johannes Schindelin1-0/+6
It is a bit cumbersome to write out the `--reschedule-failed-exec` option before `-x <cmd>` all the time; let's introduce a convenient option to do both at the same time: `-y <cmd>`. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-12-11rebase: introduce --reschedule-failed-execLibravatar Johannes Schindelin1-0/+5
A common use case for the `--exec` option is to verify that each commit in a topic branch compiles cleanly, via `git rebase -x make <base>`. However, when an `exec` in such a rebase fails, it is not re-scheduled, which in this instance is not particularly helpful. Let's offer a flag to reschedule failed `exec` commands. Based on an idea by Paul Morelle. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-12-10rebase docs: drop stray word in merge command descriptionLibravatar Kyle Meyer1-1/+1
Delete a misplaced word introduced by caafecfcf1 (rebase --rebase-merges: adjust man page for octopus support, 2018-03-09). Signed-off-by: Kyle Meyer <kyle@kyleam.com> Acked-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-12-09git-rebase.txt: update note about directory rename detection and amLibravatar Elijah Newren1-2/+3
In commit 6aba117d5cf7 ("am: avoid directory rename detection when calling recursive merge machinery", 2018-08-29), the git-rebase manpage probably should have also been updated to note the stronger incompatibility between git-am and directory rename detection. Update it now. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Johannes Sixt <j6t@kdbg.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-12-04Merge branch 'en/rebase-consistency'Libravatar Junio C Hamano1-13/+17
* en/rebase-consistency: rebase docs: fix incorrect format of the section Behavioral Differences
2018-12-04rebase docs: fix incorrect format of the section Behavioral DifferencesLibravatar Johannes Sixt1-13/+17
The text body of section Behavioral Differences is typeset as code, but should be regular text. Remove the indentation to achieve that. While here, prettify the language: - use "the x backend" instead of "x-based rebase"; - use present tense instead of future tense; and use subsections instead of a list. Signed-off-by: Johannes Sixt <j6t@kdbg.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-11-13Merge branch 'nd/config-split'Libravatar Junio C Hamano1-1/+1
Split the overly large Documentation/config.txt file into million little pieces. This potentially allows each individual piece included into the manual page of the command it affects more easily. * nd/config-split: (81 commits) config.txt: remove config/dummy.txt config.txt: move worktree.* to a separate file config.txt: move web.* to a separate file config.txt: move versionsort.* to a separate file config.txt: move user.* to a separate file config.txt: move url.* to a separate file config.txt: move uploadpack.* to a separate file config.txt: move uploadarchive.* to a separate file config.txt: move transfer.* to a separate file config.txt: move tag.* to a separate file config.txt: move submodule.* to a separate file config.txt: move stash.* to a separate file config.txt: move status.* to a separate file config.txt: move splitIndex.* to a separate file config.txt: move showBranch.* to a separate file config.txt: move sequencer.* to a separate file config.txt: move sendemail-config.txt to config/ config.txt: move reset.* to a separate file config.txt: move rerere.* to a separate file config.txt: move repack.* to a separate file ...
2018-11-02Merge branch 'js/rebase-i-break'Libravatar Junio C Hamano1-1/+5
"git rebase -i" learned a new insn, 'break', that the user can insert in the to-do list. Upon hitting it, the command returns control back to the user. * js/rebase-i-break: rebase -i: introduce the 'break' command rebase -i: clarify what happens on a failed `exec`
2018-10-29config.txt: move rebase-config.txt to config/Libravatar Nguyễn Thái Ngọc Duy1-1/+1
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-10-12rebase -i: introduce the 'break' commandLibravatar Johannes Schindelin1-0/+3
The 'edit' command can be used to cherry-pick a commit and then immediately drop out of the interactive rebase, with exit code 0, to let the user amend the commit, or test it, or look around. Sometimes this functionality would come in handy *without* cherry-picking a commit, e.g. to interrupt the interactive rebase even before cherry-picking a commit, or immediately after an 'exec' or a 'merge'. This commit introduces that functionality, as the spanking new 'break' command. Suggested-by: Stefan Beller <sbeller@google.com> Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-10-11rebase -i: clarify what happens on a failed `exec`Libravatar Johannes Schindelin1-1/+2
We had not documented previously what happens when an `exec` command in an interactive rebase fails. Now we do. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-10-07docs: typo: s/isimilar/similar/Libravatar Michael Witten1-1/+1
Signed-off-by: Michael Witten <mfwitten@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-08-02Merge branch 'js/rebase-merge-octopus'Libravatar Junio C Hamano1-3/+4
"git rebase --rebase-merges" mode now handles octopus merges as well. * js/rebase-merge-octopus: rebase --rebase-merges: adjust man page for octopus support rebase --rebase-merges: add support for octopus merges merge: allow reading the merge commit message from a file
2018-07-24Merge branch 'en/rebase-consistency'Libravatar Junio C Hamano1-27/+108
"git rebase" behaved slightly differently depending on which one of the three backends gets used; this has been documented and an effort to make them more uniform has begun. * en/rebase-consistency: git-rebase: make --allow-empty-message the default t3401: add directory rename testcases for rebase and am git-rebase.txt: document behavioral differences between modes directory-rename-detection.txt: technical docs on abilities and limitations git-rebase.txt: address confusion between --no-ff vs --force-rebase git-rebase: error out when incompatible options passed t3422: new testcases for checking when incompatible options passed git-rebase.sh: update help messages a bit git-rebase.txt: document incompatible options
2018-07-18Merge branch 'js/rebase-recreate-merge'Libravatar Junio C Hamano1-1/+1
Docfix. * js/rebase-recreate-merge: rebase: fix documentation formatting
2018-07-11rebase --rebase-merges: adjust man page for octopus supportLibravatar Johannes Schindelin1-3/+4
Now that we support octopus merges in the `--rebase-merges` mode, we should give users who actually read the manuals a chance to know about this fact. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-06-27git-rebase: make --allow-empty-message the defaultLibravatar Elijah Newren1-10/+0
rebase backends currently behave differently with empty commit messages, largely as a side-effect of the different underlying commands on which they are based. am-based rebases apply commits with an empty commit message without stopping or requiring the user to specify an extra flag. (It is interesting to note that am-based rebases are the default rebase type, and no one has ever requested a --no-allow-empty-message flag to change this behavior.) merge-based and interactive-based rebases (which are ultimately based on git-commit), will currently halt on any such commits and require the user to manually specify what to do with the commit and continue. One possible rationale for the difference in behavior is that the purpose of an "am" based rebase is solely to transplant an existing history, while an "interactive" rebase is one whose purpose is to polish a series before making it publishable. Thus, stopping and asking for confirmation for a possible problem is more appropriate in the latter case. However, there are two problems with this rationale: 1) merge-based rebases are also non-interactive and there are multiple types of rebases that use the interactive machinery but are not explicitly interactive (e.g. when either --rebase-merges or --keep-empty are specified without --interactive). These rebases are also used solely to transplant an existing history, and thus also should default to --allow-empty-message. 2) this rationale only says that the user is more accepting of stopping in the case of an explicitly interactive rebase, not that stopping for this particular reason actually makes sense. Exploring whether it makes sense, requires backing up and analyzing the underlying commands... If git-commit did not error out on empty commits by default, accidental creation of commits with empty messages would be a very common occurrence (this check has caught me many times). Further, nearly all such empty commit messages would be considered an accidental error (as evidenced by a huge amount of documentation across version control systems and in various blog posts explaining how important commit messages are). A simple check for what would otherwise be a common error thus made a lot of sense, and git-commit gained an --allow-empty-message flag for special case overrides. This has made commits with empty messages very rare. There are two sources for commits with empty messages for rebase (and cherry-pick): (a) commits created in git where the user previously specified --allow-empty-message to git-commit, and (b) commits imported into git from other version control systems. In case (a), the user has already explicitly specified that there is something special about this commit that makes them not want to specify a commit message; forcing them to re-specify with every cherry-pick or rebase seems more likely to be infuriating than helpful. In case (b), the commit is highly unlikely to have been authored by the person who has imported the history and is doing the rebase or cherry-pick, and thus the user is unlikely to be the appropriate person to write a commit message for it. Stopping and expecting the user to modify the commit before proceeding thus seems counter-productive. Further, note that while empty commit messages was a common error case for git-commit to deal with, it is a rare case for rebase (or cherry-pick). The fact that it is rare raises the question of why it would be worth checking and stopping on this particular condition and not others. For example, why doesn't an interactive rebase automatically stop if the commit message's first line is 2000 columns long, or is missing a blank line after the first line, or has every line indented with five spaces, or any number of other myriad problems? Finally, note that if a user doing an interactive rebase does have the necessary knowledge to add a message for any such commit and wants to do so, it is rather simple for them to change the appropriate line from 'pick' to 'reword'. The fact that the subject is empty in the todo list that the user edits should even serve as a way to notify them. As far as I can tell, the fact that merge-based and interactive-based rebases stop on commits with empty commit messages is solely a by-product of having been based on git-commit. It went without notice for a long time precisely because such cases are rare. The rareness of this situation made it difficult to reason about, so when folks did eventually notice this behavior, they assumed it was there for a good reason and just added an --allow-empty-message flag. In my opinion, stopping on such messages not desirable in any of these cases, even the (explicitly) interactive case. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-06-27git-rebase.txt: document behavioral differences between modesLibravatar Elijah Newren1-0/+32
There are a variety of aspects that are common to all rebases regardless of which backend is in use; however, the behavior for these different aspects varies in ways that could surprise users. (In fact, it's not clear -- to me at least -- that these differences were even desirable or intentional.) Document these differences. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-06-27git-rebase.txt: address confusion between --no-ff vs --force-rebaseLibravatar Elijah Newren1-20/+10
rebase was taught the --force-rebase option in commit b2f82e05de ("Teach rebase to rebase even if upstream is up to date", 2009-02-13). This flag worked for the am and merge backends, but wasn't a valid option for the interactive backend. rebase was taught the --no-ff option for interactive rebases in commit b499549401cb ("Teach rebase the --no-ff option.", 2010-03-24), to do the exact same thing as --force-rebase does for non-interactive rebases. This commit explicitly documented the fact that --force-rebase was incompatible with --interactive, though it made --no-ff a synonym for --force-rebase for non-interactive rebases. The choice of a new option was based on the fact that "force rebase" didn't sound like an appropriate term for the interactive machinery. In commit 6bb4e485cff8 ("rebase: align variable names", 2011-02-06), the separate parsing of command line options in the different rebase scripts was removed, and whether on accident or because the author noticed that these options did the same thing, the options became synonyms and both were accepted by all three rebase types. In commit 2d26d533a012 ("Documentation/git-rebase.txt: -f forces a rebase that would otherwise be a no-op", 2014-08-12), which reworded the description of the --force-rebase option, the (no-longer correct) sentence stating that --force-rebase was incompatible with --interactive was finally removed. Finally, as explained at https://public-inbox.org/git/98279912-0f52-969d-44a6-22242039387f@xiplink.com In the original discussion around this option [1], at one point I proposed teaching rebase--interactive to respect --force-rebase instead of adding a new option [2]. Ultimately --no-ff was chosen as the better user interface design [3], because an interactive rebase can't be "forced" to run. We have accepted both --no-ff and --force-rebase as full synonyms for all three rebase types for over seven years. Documenting them differently and in ways that suggest they might not be quite synonyms simply leads to confusion. Adjust the documentation to match reality. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-06-27rebase: fix documentation formattingLibravatar Vladimir Parfinenko1-1/+1
Last sections are squashed into non-formatted block after adding "REBASING MERGES". To reproduce the error see bottom of page: https://git-scm.com/docs/git-rebase Signed-off-by: Vladimir Parfinenko <vparfinenko@excelsior-usa.com> Acked-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-06-26git-rebase.txt: document incompatible optionsLibravatar Elijah Newren1-8/+77
git rebase has many options that only work with one of its three backends. It also has a few other pairs of incompatible options. Document these. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-05-25Use proper syntax for replaceables in command docsLibravatar Robert P. J. Day1-2/+2
The standard for command documentation synopses appears to be: [...] means optional <...> means replaceable [<...>] means both optional and replaceable So fix a number of doc pages that use incorrect variations of the above. Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-04-26rebase -i --rebase-merges: add a section to the man pageLibravatar Johannes Schindelin1-0/+135
The --rebase-merges mode is probably not half as intuitive to use as its inventor hopes, so let's document it some. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-04-26rebase -i: introduce --rebase-merges=[no-]rebase-cousinsLibravatar Johannes Schindelin1-4/+11
When running `git rebase --rebase-merges` non-interactively with an ancestor of HEAD as <upstream> (or leaving the todo list unmodified), we would ideally recreate the exact same commits as before the rebase. However, if there are commits in the commit range <upstream>.. that do not have <upstream> as direct ancestor (i.e. if `git log <upstream>..` would show commits that are omitted by `git log --ancestry-path <upstream>..`), this is currently not the case: we would turn them into commits that have <upstream> as direct ancestor. Let's illustrate that with a diagram: C / \ A - B - E - F \ / D Currently, after running `git rebase -i --rebase-merges B`, the new branch structure would be (pay particular attention to the commit `D`): --- C' -- / \ A - B ------ E' - F' \ / D' This is not really preserving the branch topology from before! The reason is that the commit `D` does not have `B` as ancestor, and therefore it gets rebased onto `B`. This is unintuitive behavior. Even worse, when recreating branch structure, most use cases would appear to want cousins *not* to be rebased onto the new base commit. For example, Git for Windows (the heaviest user of the Git garden shears, which served as the blueprint for --rebase-merges) frequently merges branches from `next` early, and these branches certainly do *not* want to be rebased. In the example above, the desired outcome would look like this: --- C' -- / \ A - B ------ E' - F' \ / -- D' -- Let's introduce the term "cousins" for such commits ("D" in the example), and let's not rebase them by default. For hypothetical use cases where cousins *do* need to be rebased, `git rebase --rebase=merges=rebase-cousins` needs to be used. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-04-26rebase: introduce the --rebase-merges optionLibravatar Johannes Schindelin1-1/+20
Once upon a time, this here developer thought: wouldn't it be nice if, say, Git for Windows' patches on top of core Git could be represented as a thicket of branches, and be rebased on top of core Git in order to maintain a cherry-pick'able set of patch series? The original attempt to answer this was: git rebase --preserve-merges. However, that experiment was never intended as an interactive option, and it only piggy-backed on git rebase --interactive because that command's implementation looked already very, very familiar: it was designed by the same person who designed --preserve-merges: yours truly. Some time later, some other developer (I am looking at you, Andreas! ;-)) decided that it would be a good idea to allow --preserve-merges to be combined with --interactive (with caveats!) and the Git maintainer (well, the interim Git maintainer during Junio's absence, that is) agreed, and that is when the glamor of the --preserve-merges design started to fall apart rather quickly and unglamorously. The reason? In --preserve-merges mode, the parents of a merge commit (or for that matter, of *any* commit) were not stated explicitly, but were *implied* by the commit name passed to the `pick` command. This made it impossible, for example, to reorder commits. Not to mention to move commits between branches or, deity forbid, to split topic branches into two. Alas, these shortcomings also prevented that mode (whose original purpose was to serve Git for Windows' needs, with the additional hope that it may be useful to others, too) from serving Git for Windows' needs. Five years later, when it became really untenable to have one unwieldy, big hodge-podge patch series of partly related, partly unrelated patches in Git for Windows that was rebased onto core Git's tags from time to time (earning the undeserved wrath of the developer of the ill-fated git-remote-hg series that first obsoleted Git for Windows' competing approach, only to be abandoned without maintainer later) was really untenable, the "Git garden shears" were born [*1*/*2*]: a script, piggy-backing on top of the interactive rebase, that would first determine the branch topology of the patches to be rebased, create a pseudo todo list for further editing, transform the result into a real todo list (making heavy use of the `exec` command to "implement" the missing todo list commands) and finally recreate the patch series on top of the new base commit. That was in 2013. And it took about three weeks to come up with the design and implement it as an out-of-tree script. Needless to say, the implementation needed quite a few years to stabilize, all the while the design itself proved itself sound. With this patch, the goodness of the Git garden shears comes to `git rebase -i` itself. Passing the `--rebase-merges` option will generate a todo list that can be understood readily, and where it is obvious how to reorder commits. New branches can be introduced by inserting `label` commands and calling `merge <label>`. And once this mode will have become stable and universally accepted, we can deprecate the design mistake that was `--preserve-merges`. Link *1*: https://github.com/msysgit/msysgit/blob/master/share/msysGit/shears.sh Link *2*: https://github.com/git-for-windows/build-extra/blob/master/shears.sh Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-04-25Merge branch 'pw/rebase-signoff'Libravatar Junio C Hamano1-3/+4
"git rebase" has learned to honor "--signoff" option when using backends other than "am" (but not "--preserve-merges"). * pw/rebase-signoff: rebase --keep-empty: always use interactive rebase rebase -p: error out if --signoff is given rebase: extend --signoff support
2018-03-29rebase: extend --signoff supportLibravatar Phillip Wood1-3/+4
Allow --signoff to be used with --interactive and --merge. In interactive mode only commits marked to be picked, edited or reworded will be signed off. The main motivation for this patch was to allow one to run 'git rebase --exec "make check" --signoff' which is useful when preparing a patch series for publication and is more convenient than doing the signoff with another --exec command. This change also allows --root without --onto to work with --signoff as well (--root with --onto was already supported). Signed-off-by: Phillip Wood <phillip.wood@dunelm.org.uk> Signed-off-by: Junio C Hamano <gitster@pobox.com>