path: root/Documentation/git-merge.txt
AgeCommit message (Collapse)Author
2013-02-01Documentation: the name of the system is 'Git', not 'git'Thomas Ackermann
Signed-off-by: Thomas Ackermann <> Signed-off-by: Junio C Hamano <>
2012-10-25Documentation: remote tracking branch -> remote-tracking branchMatthieu Moy
This change was already done by 0e615b252f3 (Matthieu Moy, Tue Nov 2 2010, Replace "remote tracking" with "remote-tracking"), but new instances of remote tracking (without dash) were introduced in the meantime. Signed-off-by: Matthieu Moy <> Signed-off-by: Jeff King <>
2012-07-15doc: A few minor copy edits.Štěpán Němec
- (glossary) the quotes around the Wikipedia URL prevented its linkification in frontends that support it; remove them - (manual) newer version (SHA-1) == following, older == preceding, not the other way around - trivial typo and wording fixes Signed-off-by: Štěpán Němec <> Signed-off-by: Junio C Hamano <>
2012-01-23merge: use editor by default in interactive sessionsJunio C Hamano
Traditionally, a cleanly resolved merge was committed by "git merge" using the auto-generated merge commit log message without invoking the editor. After 5 years of use in the field, it turns out that people perform too many unjustified merges of the upstream history into their topic branches. These merges are not just useless, but they are often not explained well, and making the end result unreadable when it gets time for merging their history back to their upstream. Earlier we added the "--edit" option to the command, so that people can edit the log message to explain and justify their merge commits. Let's take it one step further and spawn the editor by default when we are in an interactive session (i.e. the standard input and the standard output are pointing at the same tty device). There may be existing scripts that leave the standard input and the standard output of the "git merge" connected to whatever environment the scripts were started, and such invocation might trigger the above "interactive session" heuristics. GIT_MERGE_AUTOEDIT environment variable can be set to "no" at the beginning of such scripts to use the historical behaviour while the script runs. Note that this backward compatibility is meant only for scripts, and we deliberately do *not* support "merge.edit = yes/no/auto" configuration option to allow people to keep the historical behaviour. Suggested-by: Linus Torvalds <> Signed-off-by: Junio C Hamano <>
2011-04-02Merge branch 'jc/merge-sans-branch'Junio C Hamano
* jc/merge-sans-branch: merge: merge with the default upstream branch without argument merge: match the help text with the documentation Conflicts: builtin/merge.c
2011-03-24merge: merge with the default upstream branch without argumentJunio C Hamano
"git merge" without specifying any commit is a no-op by default. A new option merge.defaultupstream can be set to true to cause such an invocation of the command to merge the upstream branches configured for the current branch by using their last observed values stored in their remote tracking branches. Signed-off-by: Junio C Hamano <>
2011-03-11doc: drop author/documentation sections from most pagesJeff King
The point of these sections is generally to: 1. Give credit where it is due. 2. Give the reader an idea of where to ask questions or file bug reports. But they don't do a good job of either case. For (1), they are out of date and incomplete. A much more accurate answer can be gotten through shortlog or blame. For (2), the correct contact point is generally git@vger, and even if you wanted to cc the contact point, the out-of-date and incomplete fields mean you're likely sending to somebody useless. So let's drop the fields entirely from all manpages except git(1) itself. We already point people to the mailing list for bug reports there, and we can update the Authors section to give credit to the major contributors and point to shortlog and blame for more information. Each page has a "This is part of git" footer, so people can follow that to the main git manpage.
2010-12-08Merge branch 'jh/notes-merge'Junio C Hamano
* jh/notes-merge: (23 commits) Provide 'git merge --abort' as a synonym to 'git reset --merge' cmd_merge(): Parse options before checking MERGE_HEAD Provide 'git notes get-ref' to easily retrieve current notes ref git notes merge: Add testcases for merging notes trees at different fanouts git notes merge: Add another auto-resolving strategy: "cat_sort_uniq" git notes merge: --commit should fail if underlying notes ref has moved git notes merge: List conflicting notes in notes merge commit message git notes merge: Manual conflict resolution, part 2/2 git notes merge: Manual conflict resolution, part 1/2 Documentation: Preliminary docs on 'git notes merge' git notes merge: Add automatic conflict resolvers (ours, theirs, union) git notes merge: Handle real, non-conflicting notes merges builtin/notes.c: Refactor creation of notes commits. git notes merge: Initial implementation handling trivial merges only builtin/notes.c: Split notes ref DWIMmery into a separate function notes.c: Use two newlines (instead of one) when concatenating notes (trivial) t3303: Indent with tabs instead of spaces for consistency notes.h/c: Propagate combine_notes_fn return value to add_note() and beyond notes.h/c: Allow combine_notes functions to remove notes notes.c: Reorder functions in preparation for next commit ... Conflicts: builtin.h
2010-11-17Provide 'git merge --abort' as a synonym to 'git reset --merge'Johan Herland
Teach 'git merge' the --abort option, which verifies the existence of MERGE_HEAD and then invokes 'git reset --merge' to abort the current in-progress merge and attempt to reconstruct the pre-merge state. The reason for adding this option is to provide a user interface for aborting an in-progress merge that is consistent with the interface for aborting a rebase ('git rebase --abort'), aborting the application of a patch series ('git am --abort'), and aborting an in-progress notes merge ('git notes merge --abort'). The patch includes documentation and testcases that explain and verify the various scenarios in which 'git merge --abort' can run. The testcases also document the cases in which 'git merge --abort' is unable to correctly restore the pre-merge state (look for the '###' comments towards the bottom of t/ This patch has been improved by the following contributions: - Jonathan Nieder: Move test documentation into test_description Thanks-to: Jonathan Nieder <> Signed-off-by: Johan Herland <> Signed-off-by: Junio C Hamano <>
2010-10-29Fix a formatting error in git-merge.txtNathan W. Panike
Inside an element of an enumerated list, the second and subsequent paragraphs need to lose their indent and have to be strung together with a line with a single '+' on it instead. Otherwise the lines below are shown in typewriter face, which just looks wrong. Signed-off-by: Nathan W. Panike <> Reviewed-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2010-05-10merge: --log appends shortlog to message if specifiedTay Ray Chuan
When the user specifies a message, use fmt_merge_msg_shortlog() to append the shortlog. Previously, when a message was specified, we ignored the merge title ("Merge <foo> into <bar>") and shortlog from fmt_merge_msg(). Update the documentation for -m to reflect this too. Signed-off-by: Tay Ray Chuan <> Signed-off-by: Junio C Hamano <>
2010-04-12Docs: Add -X option to git-merge's synopsis.Marc Branchaud
Also move -X's description next to -s's in merge-options.txt. This makes it easier to learn how to specify merge strategy options. Signed-off-by: Junio C Hamano <>
2010-01-24Merge branch 'doc-style/for-next' of git:// C Hamano
* 'doc-style/for-next' of git:// Documentation: merge: use MERGE_HEAD to refer to the remote branch Documentation: simplify How Merge Works Documentation: merge: add a section about fast-forward Documentation: emphasize when git merge terminates early Documentation: merge: add an overview Documentation: merge: move merge strategy list to end Documentation: suggest `reset --merge` in How Merge Works section Documentation: merge: move configuration section to end Documentation: emphasise 'git shortlog' in its synopsis Documentation: show-files is now called git-ls-files Documentation: tiny git config manual tweaks Documentation: git gc packs refs by default now Conflicts: Documentation/config.txt
2010-01-24Documentation: merge: use MERGE_HEAD to refer to the remote branchJonathan Nieder
commit 57bddb11 (Documentation/git-merge: reword references to "remote" and "pull", 2010-01-07) fixed the manual to drop the assumption that the other branch being merged is from a remote repository. Unfortunately, in a few places, to do so it introduced the antecedentless phrase "their versions". Worse, in passages like the following, 'they' is playing two roles. | highlighting changes from both the HEAD and their versions. | | * Look at the diffs on their own. 'git log --merge -p <path>' Using HEAD and MERGE_HEAD nicely assigns terminology to "our" and "their" sides. It also provides the reader with practice using names that git will recognize on the command line. Signed-off-by: Jonathan Nieder <> Signed-off-by: Thomas Rast <>
2010-01-24Documentation: simplify How Merge WorksJonathan Nieder
The user most likely does not care about the exact order of operations because he cannot see it happening anyway. Instead, try to explain what it means to merge two commits into a single tree. While at it: - Change the heading to TRUE MERGE. The entire manual page is about how merges work. - Document MERGE_HEAD. It is a useful feature, since it makes the parents of the intended merge commit easier to refer to. - Do not assume commits named on the 'git merge' command line come from another repository. For simplicity, the discussion of conflicts still does assume that there is only one and it is a branch head. - Do not start list items with `code`. Otherwise, a toolchain bug produces a line break in the generated nroff, resulting in odd extra space. Suggested-by: Thomas Rast <> Signed-off-by: Jonathan Nieder <> Signed-off-by: Thomas Rast <>
2010-01-24Documentation: merge: add a section about fast-forwardJonathan Nieder
Novices sometimes find the behavior of 'git merge' in the fast-forward case surprising. Describe it thoroughly. Signed-off-by: Jonathan Nieder <> Signed-off-by: Thomas Rast <>
2010-01-24Documentation: emphasize when git merge terminates earlyJonathan Nieder
A merge-based operation in git can fail in two ways: one that stops before touching anything, or one that goes ahead and results in conflicts. As the 'git merge' manual explains: | A merge is always between the current `HEAD` and one or more | commits (usually, branch head or tag), and the index file must | match the tree of `HEAD` commit (i.e. the contents of the last commit) | when it starts out. Unfortunately, the placement of this sentence makes it easy to skip over, and its formulation leaves the important point, that any other attempted merge will be gracefully aborted, unspoken. So give this point its own section and expand upon it. Probably this could be simplified somewhat: after all, a change registered in the index is just a special kind of local uncommited change, so the second added paragraph is only a special case of the first. It seemed more helpful to be explicit here. Inspired by <>. Signed-off-by: Jonathan Nieder <> Signed-off-by: Thomas Rast <>
2010-01-24Documentation: merge: add an overviewJonathan Nieder
The reader unfamiliar with the concepts of branching and merging would have been completely lost. Try to help him with a diagram. Signed-off-by: Jonathan Nieder <> Signed-off-by: Thomas Rast <>
2010-01-24Documentation: merge: move merge strategy list to endJonathan Nieder
So the section layout changes as follows: NAME SYNOPSIS DESCRIPTION OPTIONS -MERGE STRATEGIES HOW MERGE WORKS HOW CONFLICTS ARE PRESENTED HOW TO RESOLVE CONFLICTS EXAMPLES +MERGE STRATEGIES CONFIGURATION SEE ALSO AUTHOR DOCUMENTATION GIT NOTES The first-time user will care more about conflicts than about strategies other than 'recursive'. One of the examples uses -s ours, but I do not think this hinders readability. Suggested-by: Thomas Rast <> Signed-off-by: Jonathan Nieder <> Signed-off-by: Thomas Rast <>
2010-01-24Documentation: suggest `reset --merge` in How Merge Works sectionJonathan Nieder
The 'merge' manual suggests 'reset' to cancel a merge at the end of the Merge Strategies list. It is more logical to explain this right before explaining how merge conflicts work, so the daunted reader can have a way out when he or she needs it most. While at it, make the advice more dependable and self-contained by providing the --merge option. Signed-off-by: Jonathan Nieder <> Signed-off-by: Thomas Rast <>
2010-01-24Documentation: merge: move configuration section to endJonathan Nieder
Configuration and environment variables belong to the back matter of a manual page. Signed-off-by: Jonathan Nieder <> Acked-by: Petr Baudis <> Signed-off-by: Thomas Rast <>
2010-01-21Merge remote branch 'remotes/trast-doc/for-next'Junio C Hamano
* remotes/trast-doc/for-next: Documentation: spell 'git cmd' without dash throughout Documentation: format full commands in typewriter font Documentation: warn prominently against merging with dirty trees Documentation/git-merge: reword references to "remote" and "pull" Conflicts: Documentation/config.txt Documentation/git-config.txt Documentation/git-merge.txt
2010-01-10Documentation: spell 'git cmd' without dash throughoutThomas Rast
The documentation was quite inconsistent when spelling 'git cmd' if it only refers to the program, not to some specific invocation syntax: both 'git-cmd' and 'git cmd' spellings exist. The current trend goes towards dashless forms, and there is precedent in 647ac70 (git-svn.txt: stop using dash-form of commands., 2009-07-07) to actively eliminate the dashed variants. Replace 'git-cmd' with 'git cmd' throughout, except where git-shell, git-cvsserver, git-upload-pack, git-receive-pack, and git-upload-archive are concerned, because those really live in the $PATH.
2010-01-10Documentation: format full commands in typewriter fontThomas Rast
Use `code snippet` style instead of 'emphasis' for `git cmd ...` according to the following rules: * The SYNOPSIS sections are left untouched. * If the intent is that the user type the command exactly as given, it is `code`. If the user is only loosely referred to a command and/or option, it remains 'emphasised'. Signed-off-by: Thomas Rast <>
2010-01-09Documentation: warn prominently against merging with dirty treesThomas Rast
We do this for both git-merge and git-pull, so as to hopefully alert (over)users of git-pull to the issue. Signed-off-by: Thomas Rast <>
2010-01-09Documentation/git-merge: reword references to "remote" and "pull"Thomas Rast
The git-merge manpage was written in terms of merging a "remote", which is no longer the case: you merge local or remote-tracking branches; pull is for actual remotes. Adjust the manpage accordingly. We refer to the arguments as "commits", and change instances of "remote" to "other" (where branches are concerned) or "theirs" (where conflict sides are concerned). Remove the single reference to "pulling". Signed-off-by: Thomas Rast <>
2009-12-04Teach --[no-]rerere-autoupdate option to merge, revert and friendsJunio C Hamano
Introduce a command line option to override rerere.autoupdate configuration variable to make it more useful. Signed-off-by: Junio C Hamano <>
2009-10-21modernize fetch/merge/pull examplesClemens Buchacher
The "git pull" documentation has examples which follow an outdated style. Update the examples to use "git merge" where appropriate and move the examples to the corresponding manpages. Furthermore, - show that pull is equivalent to fetch and merge, which is still a frequently asked question, - explain the default fetch refspec. Signed-off-by: Clemens Buchacher <> Signed-off-by: Junio C Hamano <>
2009-10-09Documentation: clarify mergeoptions descriptionJonathan Nieder
Sounds better this way, at least to my ears. ("The syntax and supported options of git merge" is a plural noun. "the same" instead of "equal" sounds less technical and seems to convey the meaning better here.) Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2009-10-09Documentation: git fmt-merge-msg does not have to be a scriptJonathan Nieder
The fmt-merge-message builtin can be invoked as "git fmt-merge-msg" rather than through the hard link in GIT_EXEC_PATH. Although this is unlikely to confuse most script writers, it should not hurt to make the documentation a little clearer anyway. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2009-08-12Documentation: merge: one <remote> is requiredPaul Bolle
merge only requires one <remote>, so "<remote>..." should be used in the synopsis (and not "<remote> <remote>..."). Signed-off-by: Paul Bolle <> Signed-off-by: Junio C Hamano <>
2009-03-26Grammar fix for "git merge" man pageWincent Colaiuta
As spotted by the eagle eyes of Jeff King. Signed-off-by: Wincent Colaiuta <> Signed-off-by: Junio C Hamano <>
2009-03-26Grammar fixes to "merge" and "patch-id" docsWincent Colaiuta
Signed-off-by: Wincent Colaiuta <> Signed-off-by: Junio C Hamano <>
2009-03-17Documentation: remove extra quoting/emphasis around literal textsChris Johnsen
If literal text (asciidoc `...`) can be rendered in a differently from normal text for each output format (man, HTML), then we do not need extra quotes or other wrapping around inline literal text segments. config.txt Change '`...`' to `...`. In asciidoc, the single quotes provide emphasis, literal text should be distintive enough. Change "`...`" to `...`. These double quotes do not work if present in the described config value, so drop them. git-checkout.txt Change "`...`" to `...` or `"..."`. All instances are command line argument examples. One "`-`" becomes `-`. Two others are involve curly braces, so move the double quotes inside the literal region to indicate that they might need to be quoted on the command line of certain shells (tcsh). git-merge.txt Change "`...`" to `...`. All instances are used to describe merge conflict markers. The quotes should are not important. git-rev-parse.txt Change "`...`" to `...`. All instances are around command line arguments where no in-shell quoting should be necessary. gitcli.txt Change `"..."` to `...`. All instances are around command line examples or single command arguments. They do not semanticly belong inside the literal text, and they are not needed outside it. glossary-content.txt user-manual.txt Change "`...`" to `...`. All instances were around command lines. Signed-off-by: Chris Johnsen <> Signed-off-by: Junio C Hamano <>
2008-12-10Improve language in git-merge.txt and related docsRalf Wildenhues
Improve some minor language and format issues like hyphenation, phrases, spacing, word order, comma, attributes. Signed-off-by: Junio C Hamano <>
2008-09-29Merge branch 'jc/better-conflict-resolution'Shawn O. Pearce
* jc/better-conflict-resolution: Fix AsciiDoc errors in merge documentation git-merge documentation: describe how conflict is presented checkout --conflict=<style>: recreate merge in a non-default style checkout -m: recreate merge when checking out of unmerged index git-merge-recursive: learn to honor merge.conflictstyle merge.conflictstyle: choose between "merge" and "diff3 -m" styles rerere: understand "diff3 -m" style conflicts with the original rerere.c: use symbolic constants to keep track of parsing states xmerge.c: "diff3 -m" style clips merge reduction level to EAGER or less xmerge.c: minimum readability fixups xdiff-merge: optionally show conflicts in "diff3 -m" style xdl_fill_merge_buffer(): separate out a too deeply nested function checkout --ours/--theirs: allow checking out one side of a conflicting merge checkout -f: allow ignoring unmerged paths when checking out of the index Conflicts: Documentation/git-checkout.txt builtin-checkout.c builtin-merge-recursive.c t/
2008-09-04Fix AsciiDoc errors in merge documentationJohan Herland
In the section on conflict markers, the "<<<<<<<" sequence is compiled by AsciiDoc into invalid XML. A way to resolve this is by inserting something between the last two characters in that sequence (i.e. between '<' and '"'). This patch encloses the conflict markers in backticks, which renders them in a monospace font (in the HTML version; the manual page is unaffected), and with the pleasant side-effect that it also fixes the AsciiDoc compile problem. Signed-off-by: Johan Herland <> Signed-off-by: Junio C Hamano <>
2008-09-01git-merge documentation: describe how conflict is presentedJunio C Hamano
We took it granted that everybody knows how to read the RCS merge style conflicts, and did not give illustrations in the documentation. Now we are introducing an alternative output style, it is time to document this. The lack of illustration has been bugging me for a long time. Signed-off-by: Junio C Hamano <>
2008-08-23git-merge documentation: more details about resolving conflictsDan Hensgen
Signed-off-by: Dan Hensgen <> Signed-off-by: Junio C Hamano <>
2008-07-31Make the DESCRIPTION match <x>... items in the SYNOPSISAbhijit Menon-Sen
When the SYNOPSIS says e.g. "<path>...", it is nice if the DESCRIPTION also mentions "<path>..." and says the specified "paths" (note plural) are used for $whatever. This fixes the obvious mismatches. Signed-off-by: Abhijit Menon-Sen <> Signed-off-by: Junio C Hamano <>
2008-07-21Update my e-mail addressJunio C Hamano
The old address is still getting mails from gitters. Signed-off-by: Junio C Hamano <>
2008-07-19Documentation/git-merge.txt: Partial rewrite of How Merge WorksPetr Baudis
The git-merge documentation's "HOW MERGE WORKS" section is confusingly composed and actually omits the most interesting part, the merging of the arguments into HEAD itself, surprisingly not actually mentioning the fast-forward merge anywhere. This patch replaces the "[NOTE]" screenful of highly technical details by a single sentence summing up the interesting information, and instead explains how are the arguments compared with HEAD and the three possible inclusion states that are named "Already up-to-date", "Fast-forward" and "True merge". It also makes it clear that the rest of the section talks only about the true merge situation, and slightly expands the talk on solving conflicts. Junio initiated the removal of the Note screenful altogether and offered many stylistical fixes. Signed-off-by: Petr Baudis <> Signed-off-by: Junio C Hamano <>
2008-07-08Documentation: mention ORIG_HEAD in am, merge, and rebaseBrian Gernhardt
Merge has always set ORIG_HEAD but never mentioned it, while we recently added it to am and rebase. These facts should be reflected in the documentation. git-reset also sets ORIG_HEAD, but that fact is already mentioned in the very first example so no changes were needed there. Signed-off-by: Brian Gernhardt <> Signed-off-by: Junio C Hamano <>
2008-07-05manpages: italicize git command names (which were in teletype font)Jonathan Nieder
The names of git commands are not meant to be entered at the commandline; they are just names. So we render them in italics, as is usual for command names in manpages. Using doit () { perl -e 'for (<>) { s/\`(git-[^\`.]*)\`/'\''\1'\''/g; print }' } for i in git*.txt config.txt diff*.txt blame*.txt fetch*.txt i18n.txt \ merge*.txt pretty*.txt pull*.txt rev*.txt urls*.txt do doit <"$i" >"$i+" && mv "$i+" "$i" done git diff . Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2008-07-02Documentation formatting and cleanupJonathan Nieder
Following what appears to be the predominant style, format names of commands and commandlines both as `teletype text`. While we're at it, add articles ("a" and "the") in some places, italicize the name of the command in the manual page synopsis line, and add a comma or two where it seems appropriate. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2008-07-02Documentation: be consistent about "git-" versus "git "Jonathan Nieder
Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2008-06-06documentation: move git(7) to git(1)Christian Couder
As the "git" man page describes the "git" command at the end-user level, it seems better to move it to man section 1. Signed-off-by: Christian Couder <> Signed-off-by: Junio C Hamano <>
2008-04-13merge, pull: introduce '--(no-)stat' optionSZEDER Gábor
This option has the same effect as '--(no-)summary' (i.e. whether to show a diffsat at the end of the merge or not), and it is consistent with the '--stat' option of other git commands. Documentation, tests, and bash completion are updaed accordingly, and the old --summary option is marked as being deprected. Signed-off-by: SZEDER Gábor <> Signed-off-by: Junio C Hamano <>
2008-04-13doc: moved merge.* config variables into separate merge-config.txtSZEDER Gábor
Include the new file from config.txt and git-merge.txt. Signed-off-by: SZEDER Gábor <> Signed-off-by: Junio C Hamano <>
2008-03-03Fix incorrect wording in git-merge.txt.Matthieu Moy
A merge is not necessarily with a remote branch, it can be with any commit. Thanks to Paolo Ciarrocchi for pointing out the problem, and to Nicolas Pitre for pointing out the fact that a merge is not necessarily with a branch head. Signed-off-by: Matthieu Moy <> Signed-off-by: Junio C Hamano <>