summaryrefslogtreecommitdiff
path: root/Documentation/git-merge.txt
AgeCommit message (Collapse)AuthorFilesLines
2017-08-26Merge branch 'mg/killed-merge'Libravatar Junio C Hamano1-1/+4
Killing "git merge --edit" before the editor returns control left the repository in a state with MERGE_MSG but without MERGE_HEAD, which incorrectly tells the subsequent "git commit" that there was a squash merge in progress. This has been fixed. * mg/killed-merge: merge: save merge state earlier merge: split write_merge_state in two merge: clarify call chain Documentation/git-merge: explain --continue
2017-08-21Documentation/git-merge: explain --continueLibravatar Michael J Gruber1-1/+4
Currently, 'git merge --continue' is mentioned but not explained. Explain it. Signed-off-by: Michael J Gruber <git@grubix.eu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-07-25merge: add a --signoff flagLibravatar Łukasz Gryglicki1-0/+8
Some projects require every commit, even merges, to be signed off [*1*]. Because "git merge" does not have a "--signoff" option like "git commit" does, the user needs to add one manually when the command presents an editor to describe the merge, or later use "git commit --amend --signoff". Help developers of these projects by teaching "--signoff" option to "git merge". *1* https://public-inbox.org/git/CAHv71zK5SqbwrBFX=a8-DY9H3KT4FEyMgv__p2gZzNr0WUAPUw@mail.gmail.com/T/#u Requested-by: Dan Kohn <dan@linuxfoundation.org> Signed-off-by: Łukasz Gryglicki <lukaszgryglicki@o2.pl> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-03-30Merge branch 'jc/merge-drop-old-syntax'Libravatar Junio C Hamano1-6/+1
Stop supporting "git merge <message> HEAD <commit>" syntax that has been deprecated since October 2007, and issues a deprecation warning message since v2.5.0. * jc/merge-drop-old-syntax: merge: drop 'git merge <message> HEAD <commit>' syntax
2016-12-14merge: add '--continue' option as a synonym for 'git commit'Libravatar Chris Packham1-0/+8
Teach 'git merge' the --continue option which allows 'continuing' a merge by completing it. The traditional way of completing a merge after resolving conflicts is to use 'git commit'. Now with commands like 'git rebase' and 'git cherry-pick' having a '--continue' option adding such an option to 'git merge' presents a consistent UI. Signed-off-by: Chris Packham <judge.packham@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-04-21pull: pass --allow-unrelated-histories to "git merge"Libravatar Junio C Hamano1-13/+1
The previous commit said: We could add the same option to "git pull" and have it passed through to underlying "git merge". I do not have a fundamental opposition against such a feature, but this commit does not do so and instead leaves it as low-hanging fruit for others, because such a "two project merge" would be done after fetching the other project into some location in the working tree of an existing project and making sure how well they fit together, it is sufficient to allow a local merge without such an option pass-through from "git pull" to "git merge". Prepare a patch to make it a reality, just in case it is needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-03-23merge: refuse to create too cool a merge by defaultLibravatar Junio C Hamano1-0/+13
While it makes sense to allow merging unrelated histories of two projects that started independently into one, in the way "gitk" was merged to "git" itself aka "the coolest merge ever", such a merge is still an unusual event. Worse, if somebody creates an independent history by starting from a tarball of an established project and sends a pull request to the original project, "git merge" however happily creates such a merge without any sign of something unusual is happening. Teach "git merge" to refuse to create such a merge by default, unless the user passes a new "--allow-unrelated-histories" option to tell it that the user is aware that two unrelated projects are merged. Because such a "two project merge" is a rare event, a configuration option to always allow such a merge is not added. We could add the same option to "git pull" and have it passed through to underlying "git merge". I do not have a fundamental opposition against such a feature, but this commit does not do so and instead leaves it as low-hanging fruit for others, because such a "two project merge" would be done after fetching the other project into some location in the working tree of an existing project and making sure how well they fit together, it is sufficient to allow a local merge without such an option pass-through from "git pull" to "git merge". Many tests that are updated by this patch does the pass-through manually by turning: git pull something into its equivalent: git fetch something && git merge --allow-unrelated-histories FETCH_HEAD If somebody is inclined to add such an option, updated tests in this change need to be adjusted back to: git pull --allow-unrelated-histories something Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-10-05Merge branch 'mm/keyid-docs'Libravatar Junio C Hamano1-2/+4
Very small number of options take a parameter that is optional (which is not a great UI element as they can only appear at the end of the command line). Add notice to documentation of each and every one of them. * mm/keyid-docs: Documentation: explain optional arguments better Documentation/grep: fix documentation of -O Documentation: use 'keyid' consistently, not 'key-id'
2015-09-21Documentation: explain optional arguments betterLibravatar Matthieu Moy1-1/+3
Improve the documentation of commands taking optional arguments in two ways: * Documents the behavior of '-O' (for grep) and '-S' (for commands creating commits) when used without the optional argument. * Document the syntax of these options. For the second point, the behavior is documented in gitcli(7), but it is easy for users to miss, and hard for the same user to understand why e.g. "git status -u no" does not work. Document this explicitly in the documentation of each short option having an optional argument: they are the most error prone since there is no '=' sign between the option and its argument. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Reviewed-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-09-21Documentation: use 'keyid' consistently, not 'key-id'Libravatar Matthieu Moy1-1/+1
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Reviewed-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-09-17Merge branch 'po/doc-branch-desc'Libravatar Junio C Hamano1-1/+1
The branch descriptions that are set with "git branch --edit-description" option were used in many places but they weren't clearly documented. * po/doc-branch-desc: doc: show usage of branch description
2015-09-14doc: show usage of branch descriptionLibravatar Philip Oakley1-1/+1
The branch description will be included in 'git format-patch --cover-letter' and in 'git pull-request' emails. It can also be used in the automatic merge message. Tell the reader. While here, clarify that the description may be a multi-line explanation of the purpose of the branch's patch series. Signed-off-by: Philip Oakley <philipoakley@iee.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-05-19Merge branch 'jc/merge'Libravatar Junio C Hamano1-0/+4
"git merge FETCH_HEAD" learned that the previous "git fetch" could be to create an Octopus merge, i.e. recording multiple branches that are not marked as "not-for-merge"; this allows us to lose an old style invocation "git merge <msg> HEAD $commits..." in the implementation of "git pull" script; the old style syntax can now be deprecated. * jc/merge: merge: deprecate 'git merge <message> HEAD <commit>' syntax merge: handle FETCH_HEAD internally merge: decide if we auto-generate the message early in collect_parents() merge: make collect_parents() auto-generate the merge message merge: extract prepare_merge_message() logic out merge: narrow scope of merge_names merge: split reduce_parents() out of collect_parents() merge: clarify collect_parents() logic merge: small leakfix and code simplification merge: do not check argc to determine number of remote heads merge: clarify "pulling into void" special case t5520: test pulling an octopus into an unborn branch t5520: style fixes merge: simplify code flow merge: test the top-level merge driver
2015-04-29merge: drop 'git merge <message> HEAD <commit>' syntaxLibravatar Junio C Hamano1-6/+1
And then if we and our users survived the previous "start warning if the old syntax is used" patch for a few years, we could apply this to actually drop the support for the ancient syntax. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-04-29merge: handle FETCH_HEAD internallyLibravatar Junio C Hamano1-0/+4
The collect_parents() function now is responsible for 1. parsing the commits given on the command line into a list of commits to be merged; 2. filtering these parents into independent ones; and 3. optionally calling fmt_merge_msg() via prepare_merge_message() to prepare an auto-generated merge log message, using fake contents that FETCH_HEAD would have had if these commits were fetched from the current repository with "git pull . $args..." Make "git merge FETCH_HEAD" to be the same as the traditional git merge "$(git fmt-merge-msg <.git/FETCH_HEAD)" $commits invocation of the command in "git pull", where $commits are the ones that appear in FETCH_HEAD that are not marked as not-for-merge, by making it do a bit more, specifically: - noticing "FETCH_HEAD" is the only "commit" on the command line and picking the commits that are not marked as not-for-merge as the list of commits to be merged (substitute for step #1 above); - letting the resulting list fed to step #2 above; - doing the step #3 above, using the contents of the FETCH_HEAD instead of fake contents crafted from the list of commits parsed in the step #1 above. Note that this changes the semantics. "git merge FETCH_HEAD" has always behaved as if the first commit in the FETCH_HEAD file were directly specified on the command line, creating a two-way merge whose auto-generated merge log said "merge commit xyz". With this change, if the previous fetch was to grab multiple branches (e.g. "git fetch $there topic-a topic-b"), the new world order is to create an octopus, behaving as if "git pull $there topic-a topic-b" were run. This is a deliberate change to make that happen, and can be seen in the changes to t3033 tests. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-03-13*config.txt: stick to camelCase naming conventionLibravatar Nguyễn Thái Ngọc Duy1-2/+2
This should improve readability. Compare "thislongname" and "thisLongName". The following keys are left in unchanged. We can decide what to do with them later. - am.keepcr - core.autocrlf .safecrlf .trustctime - diff.dirstat .noprefix - gitcvs.usecrlfattr - gui.blamehistoryctx .trustmtime - pull.twohead - receive.autogc - sendemail.signedoffbycc .smtpsslcertpath .suppresscc Helped-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-04-22merge: enable defaulttoupstream by defaultLibravatar Felipe Contreras1-3/+2
There's no point in this: % git merge fatal: No commit specified and merge.defaultToUpstream not set. We know the most likely scenario is that the user wants to merge the upstream, and if not, he can set merge.defaultToUpstream to false. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-03-24parse-options: multi-word argh should use dash to separate wordsLibravatar Junio C Hamano1-1/+1
"When you need to use space, use dash" is a strange way to say that you must not use a space. Because it is more common for the command line descriptions to use dashed-multi-words, you do not even want to use spaces in these places. Rephrase the documentation to avoid this strangeness. Fix a few existing multi-word argument help strings, i.e. - GPG key-ids given to -S/--gpg-sign are "key-id"; - Refs used for storing notes are "notes-ref"; and - Expiry timestamps given to --expire are "expiry-date". and update the corresponding documentation pages. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-10-18git-merge: document the -S optionLibravatar Nicolas Vigier1-1/+5
The option to gpg sign a merge commit is available but was not documented. Use wording from the git-commit(1) manpage. Signed-off-by: Nicolas Vigier <boklm@mars-attacks.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-09-05Merge branch 'maint-1.8.2' into maint-1.8.3Libravatar Junio C Hamano1-2/+2
* maint-1.8.2: Documentation/git-merge.txt: fix formatting of example block
2013-09-05Documentation/git-merge.txt: fix formatting of example blockLibravatar Andreas Schwab1-2/+2
You need at least four dashes in a line to have it recognized as listing block delimiter by asciidoc. Signed-off-by: Andreas Schwab <schwab@linux-m68k.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-07-21Merge branch 'mm/merge-in-dirty-worktree-doc' into maintLibravatar Junio C Hamano1-2/+2
* mm/merge-in-dirty-worktree-doc: Documentation/git-merge.txt: weaken warning about uncommited changes
2013-06-18Documentation/git-merge.txt: weaken warning about uncommited changesLibravatar Matthieu Moy1-2/+2
Commit 35d2fffd introduced 'git merge --abort' as a synonym to 'git reset --merge', and added some failing tests in t7611-merge-abort.sh (search '###' in this file) showing that 'git merge --abort' could not always recover the pre-merge state. Still, in many cases, 'git merge --abort' just works, and it is usually considered that the ability to start a merge with uncommited changes is an important property of Git. Weaken the warning by discouraging only merge with /non-trivial/ uncommited changes. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-05-17documentation: trivial style cleanupsLibravatar Felipe Contreras1-2/+1
White-spaces, missing braces, standardize --[no-]foo. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-04-01Merge branch 'yd/doc-merge-annotated-tag' into maintLibravatar Junio C Hamano1-0/+24
* yd/doc-merge-annotated-tag: Documentation: merging a tag is a special case
2013-03-28Merge branch 'yd/doc-merge-annotated-tag'Libravatar Junio C Hamano1-0/+24
Document the 1.7.9 feature to merge a signed tag and keep that in the mergetag header in the resulting commit better. * yd/doc-merge-annotated-tag: Documentation: merging a tag is a special case
2013-03-21Documentation: merging a tag is a special caseLibravatar Junio C Hamano1-0/+24
When asking Git to merge a tag (such as a signed tag or annotated tag), it will always create a merge commit even if fast-forward was possible. It's like having --no-ff present on the command line. It's a difference from the default behavior described in git-merge.txt. It should be documented as an exception of "FAST-FORWARD MERGE" section and "--ff" option description. Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Reviewed-by: Yann Droneaud <ydroneaud@opteya.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-01Documentation: the name of the system is 'Git', not 'git'Libravatar Thomas Ackermann1-2/+2
Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-10-25Documentation: remote tracking branch -> remote-tracking branchLibravatar Matthieu Moy1-1/+1
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 <Matthieu.Moy@imag.fr> Signed-off-by: Jeff King <peff@peff.net>
2012-07-14doc: A few minor copy edits.Libravatar Štěpán Němec1-1/+1
- (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 <stepnem@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-01-23merge: use editor by default in interactive sessionsLibravatar Junio C Hamano1-1/+1
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 <torvalds@linux-foundation.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-04-01Merge branch 'jc/merge-sans-branch'Libravatar Junio C Hamano1-3/+8
* 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 argumentLibravatar Junio C Hamano1-3/+8
"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 <gitster@pobox.com>
2011-03-11doc: drop author/documentation sections from most pagesLibravatar Jeff King1-9/+0
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'Libravatar Junio C Hamano1-3/+24
* 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'Libravatar Johan Herland1-3/+24
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/t7609-merge-abort.sh). This patch has been improved by the following contributions: - Jonathan Nieder: Move test documentation into test_description Thanks-to: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Johan Herland <johan@herland.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-10-29Fix a formatting error in git-merge.txtLibravatar Nathan W. Panike1-7/+7
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 <nathan.panike@gmail.com> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-05-10merge: --log appends shortlog to message if specifiedLibravatar Tay Ray Chuan1-1/+6
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 <rctay89@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-04-12Docs: Add -X option to git-merge's synopsis.Libravatar Marc Branchaud1-1/+2
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 <gitster@pobox.com>
2010-01-24Merge branch 'doc-style/for-next' of git://repo.or.cz/git/trastLibravatar Junio C Hamano1-78/+100
* 'doc-style/for-next' of git://repo.or.cz/git/trast: 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 branchLibravatar Jonathan Nieder1-6/+8
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 <jrnieder@gmail.com> Signed-off-by: Thomas Rast <trast@student.ethz.ch>
2010-01-24Documentation: simplify How Merge WorksLibravatar Jonathan Nieder1-36/+16
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 <trast@student.ethz.ch> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Thomas Rast <trast@student.ethz.ch>
2010-01-24Documentation: merge: add a section about fast-forwardLibravatar Jonathan Nieder1-13/+18
Novices sometimes find the behavior of 'git merge' in the fast-forward case surprising. Describe it thoroughly. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Thomas Rast <trast@student.ethz.ch>
2010-01-24Documentation: emphasize when git merge terminates earlyLibravatar Jonathan Nieder1-10/+21
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 <http://gitster.livejournal.com/25801.html>. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Thomas Rast <trast@student.ethz.ch>
2010-01-24Documentation: merge: add an overviewLibravatar Jonathan Nieder1-2/+26
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 <jrnieder@gmail.com> Signed-off-by: Thomas Rast <trast@student.ethz.ch>
2010-01-24Documentation: merge: move merge strategy list to endLibravatar Jonathan Nieder1-2/+2
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 <trast@student.ethz.ch> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Thomas Rast <trast@student.ethz.ch>
2010-01-24Documentation: suggest `reset --merge` in How Merge Works sectionLibravatar Jonathan Nieder1-3/+3
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 <jrnieder@gmail.com> Signed-off-by: Thomas Rast <trast@student.ethz.ch>
2010-01-24Documentation: merge: move configuration section to endLibravatar Jonathan Nieder1-9/+9
Configuration and environment variables belong to the back matter of a manual page. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Acked-by: Petr Baudis <pasky@suse.cz> Signed-off-by: Thomas Rast <trast@student.ethz.ch>
2010-01-20Merge remote branch 'remotes/trast-doc/for-next'Libravatar Junio C Hamano1-25/+29
* 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 throughoutLibravatar Thomas Rast1-3/+3
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.