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: NJonathan Nieder <jrnieder@gmail.com>
Signed-off-by: NThomas Rast <trast@student.ethz.ch>

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: NThomas Rast <trast@student.ethz.ch>
Signed-off-by: NJonathan Nieder <jrnieder@gmail.com>
Signed-off-by: NThomas Rast <trast@student.ethz.ch>

Novices sometimes find the behavior of 'git merge' in the
fast-forward case surprising.  Describe it thoroughly.
Signed-off-by: NJonathan Nieder <jrnieder@gmail.com>
Signed-off-by: NThomas Rast <trast@student.ethz.ch>

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: NJonathan Nieder <jrnieder@gmail.com>
Signed-off-by: NThomas Rast <trast@student.ethz.ch>

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: NJonathan Nieder <jrnieder@gmail.com>
Signed-off-by: NThomas Rast <trast@student.ethz.ch>

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: NThomas Rast <trast@student.ethz.ch>
Signed-off-by: NJonathan Nieder <jrnieder@gmail.com>
Signed-off-by: NThomas Rast <trast@student.ethz.ch>

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: NJonathan Nieder <jrnieder@gmail.com>
Signed-off-by: NThomas Rast <trast@student.ethz.ch>

Configuration and environment variables belong to the back matter
of a manual page.
Signed-off-by: NJonathan Nieder <jrnieder@gmail.com>
Acked-by: NPetr Baudis <pasky@suse.cz>
Signed-off-by: NThomas Rast <trast@student.ethz.ch>

The accepted style in the SYNOPSIS section is for a command to be
'emphasised'.  Do so for the git-shortlog(1) manpage.
Signed-off-by: NThomas Rast <trast@student.ethz.ch>

Amazingly, a reference to 'show files' survived from the core command
documentation introduced in c64b9b88 (Reference documentation for the
core git commands., 2005-05-05)!

However, the tool is now called git-ls-files.
Signed-off-by: NThomas Rast <trast@student.ethz.ch>

As a verb, 'setup' is spelled 'set up'.  “diff commands such as
diff-files” scans better without a comma.  Clarify that shallow
and deep are special non-boolean values for format.thread rather
than boolean values with some other name.
Signed-off-by: NJonathan Nieder <jrnieder@gmail.com>
Signed-off-by: NThomas Rast <trast@student.ethz.ch>

In commit 56752391 (Make "git gc" pack all refs by default,
2007-05-24), 'git gc' was changed to run pack-refs by default

Versions before v1.5.1.2 cannot clone repos with packed refs over
http, and versions before v1.4.4 cannot handled packed refs at
all, but more recent git should have no problems.  Try to make
this more clear in the git-config manual.

The analagous passage in git-gc.txt was updated already with
commit fe2128a8 (Change git-gc documentation to reflect
gc.packrefs implementation., 2008-01-09).
Signed-off-by: NJonathan Nieder <jrnieder@gmail.com>
Signed-off-by: NThomas Rast <trast@student.ethz.ch>

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 647ac702 (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.

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: NThomas Rast <trast@student.ethz.ch>

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: NThomas Rast <trast@student.ethz.ch>

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: NThomas Rast <trast@student.ethz.ch>

Signed-off-by: NJunio C Hamano <gitster@pobox.com>

* js/filter-branch-prime:
  filter-branch: remove an unnecessary use of 'git read-tree'

* sb/maint-octopus:
  octopus: remove dead code
  octopus: reenable fast-forward merges
  octopus: make merge process simpler to follow

Conflicts:
	git-merge-octopus.sh

* mg/tag-d-show:
  tag -d: print sha1 of deleted tag

* so/cvsserver-update:
  cvsserver: make the output of 'update' more compatible with cvs.

* bg/maint-add-all-doc:
  git-rm doc: Describe how to sync index & work tree
  git-add/rm doc: Consistently back-quote
  Documentation: 'git add -A' can remove files

Newcomers to git that want to remove from the index only the
files that have disappeared from the working tree will probably
look for a way to do that in the documentation for 'git rm'.

Therefore, describe how that can be done (even though it involves
other commands than 'git rm'). Based on a suggestion by Junio,
but re-arranged and rewritten to better fit into the style of
command reference.

While at it, change a single occurrence of "work tree" to "working
tree" for consistency.
Signed-off-by: NBjörn Gustavsson <bgustavsson@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

* mv/commit-date:
  Document date formats accepted by parse_date()
  builtin-commit: add --date option

* mo/bin-wrappers:
  INSTALL: document a simpler way to run uninstalled builds
  run test suite without dashed git-commands in PATH
  build dashless "bin-wrappers" directory similar to installed bindir

Signed-off-by: NJunio C Hamano <gitster@pobox.com>

The %.o: %.S pattern rule should depend on GIT-CFLAGS to avoid
trouble when ALL_CFLAGS changes.

The pattern only applies to one file (ppc/sha1ppc.S) and that
file does not use any #ifdefs, so leaving the dependency out is
probably harmless.  Nevertheless, it is safer to include the
dependency in case future code's behavior does depend on the
build flags.
Signed-off-by: NJonathan Nieder <jrnieder@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NThiago Farina <tfransosi@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

* maint:
  stash: mention --patch in usage string.

Signed-off-by: NMatthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

* maint:
  branch: die explicitly why when calling "git branch [-a|-r] branchname".
  fast-import: Document author/committer/tagger name is optional
  SubmittingPatches: hints to know the status of a submitted patch.

* maint-1.6.0:
  branch: die explicitly why when calling "git branch [-a|-r] branchname".

The -a and -r options used to be silently ignored in such a command.
Signed-off-by: NMatthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

The fast-import parser does not validate that the author, committer
or tagger name component contains both a name and an email address.
Therefore the name component has always been optional.  Correct the
documentation to match the implementation.
Signed-off-by: NShawn O. Pearce <spearce@spearce.org>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

"What happened to my patch" is pretty much a FAQ on the Git mailing list,
it deserves a few paragraphs in SubmittingPatches...
Signed-off-by: NMatthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Native cvs update outputs the string "cvs update: Updating <DIR>" for
every directory it processes (to stderr) unless -q or -Q is given on
comman-line. This is used, e.g., by emacs pcl-cvs to split files by
directory. This commit implements this feature in cvsserver.
Signed-off-by: NSergei Organov <osv@javad.com>
Acked-by: NMartin Langhoff <martin.langhoff@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Improve the readability of the bash prompt by adding a space between
the branch name and the status flags (dirty, stash, untracked).

While we are cleaning up this section of code, the two cases for
formatting the prompt are identical except for the format string,
so make them the same.
Suggested-by: NRoman Fietze <roman.fietze@telemotive.de>
Signed-off-by: NShawn O. Pearce <spearce@spearce.org>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NRobert Zeh <robert.a.zeh@gmail.com>
Acked-by: NShawn O. Pearce <spearce@spearce.org>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

* maint:
  textconv: stop leaking file descriptors
  commit: --cleanup is a message option
  git count-objects: handle packs bigger than 4G
  t7102: make the test fail if one of its check fails
  Documentation: always respect core.worktree if set

* maint-1.6.1:
  textconv: stop leaking file descriptors
  commit: --cleanup is a message option
  git count-objects: handle packs bigger than 4G
  t7102: make the test fail if one of its check fails

Conflicts:
	builtin-commit.c
	diff.c