[PATCH 1/2] Documentation/git-merge: reword references to "remote" and "pull"

[PATCH 1/2] Documentation/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 <trast@student.ethz.ch>
---

Out of sheer curiosity:

  The git-merge manpage was written in terms of merging a "remote",
  which is no longer the case

Was this ever the case?  Or is it just stale terminology?


 Documentation/git-merge.txt |   32 ++++++++++++++++----------------
 1 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index e886c2e..7dbde7a 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -10,17 +10,17 @@ SYNOPSIS
 --------
 [verse]
 'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]...
-	[-m <msg>] <remote>...
-'git merge' <msg> HEAD <remote>...
+	[-m <msg>] <commit>...
+'git merge' <msg> HEAD <commit>...
 
 DESCRIPTION
 -----------
-This is the top-level interface to the merge machinery
-which drives multiple merge strategy scripts.
+Merges the history specified by <commit> into HEAD, optionally using a
+specific merge strategy.
 
-The second syntax (<msg> `HEAD` <remote>) is supported for
+The second syntax (<msg> `HEAD` <commit>...) is supported for
 historical reasons.  Do not use it from the command line or in
-new scripts.  It is the same as `git merge -m <msg> <remote>`.
+new scripts.  It is the same as `git merge -m <msg> <commit>...`.
 
 
 OPTIONS
@@ -33,10 +33,10 @@ include::merge-options.txt[]
 	used to give a good default for automated 'git merge'
 	invocations.
 
-<remote>...::
-	Other branch heads to merge into our branch.  You need at
-	least one <remote>.  Specifying more than one <remote>
-	obviously means you are trying an Octopus.
+<commit>...::
+	Commits, usually other branch heads, to merge into our branch.
+	You need at least one <commit>.  Specifying more than one
+	<commit> obviously means you are trying an Octopus.
 
 include::merge-strategies.txt[]
 
@@ -96,8 +96,8 @@ file matches exactly the current `HEAD` commit; otherwise we
 will write out your local changes already registered in your
 index file along with the merge result, which is not good.
 Because 1. involves only those paths differing between your
-branch and the remote branch you are pulling from during the
-merge (which is typically a fraction of the whole tree), you can
+branch and the branch you are merging
+(which is typically a fraction of the whole tree), you can
 have local modifications in your working tree as long as they do
 not overlap with what the merge updates.
 
@@ -110,7 +110,7 @@ When there are conflicts, the following happens:
 
 3. For conflicting paths, the index file records up to three
    versions; stage1 stores the version from the common ancestor,
-   stage2 from `HEAD`, and stage3 from the remote branch (you
+   stage2 from `HEAD`, and stage3 from the other branch (you
    can inspect the stages with `git ls-files -u`).  The working
    tree files contain the result of the "merge" program; i.e. 3-way
    merge results with familiar conflict markers `<<< === >>>`.
@@ -202,15 +202,15 @@ You can work through the conflict with a number of tools:
    mergetool which will work you through the merge.
 
  * Look at the diffs.  'git diff' will show a three-way diff,
-   highlighting changes from both the HEAD and remote versions.
+   highlighting changes from both the HEAD and 'theirs' versions.
 
  * Look at the diffs on their own. 'git log --merge -p <path>'
    will show diffs first for the HEAD version and then the
-   remote version.
+   'theirs' version.
 
  * Look at the originals.  'git show :1:filename' shows the
    common ancestor, 'git show :2:filename' shows the HEAD
-   version and 'git show :3:filename' shows the remote version.
+   version and 'git show :3:filename' shows 'their' version.
 
 
 EXAMPLES
-- 
1.6.6.202.gdf32a

[PATCH 2/2] Documentation: warn prominently against merging with dirty trees

[Thomas 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 <trast@student.ethz.ch>
---
 Documentation/git-merge.txt |    4 ++++
 Documentation/git-pull.txt  |    4 ++++
 2 files changed, 8 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 7dbde7a..b224daf 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -22,6 +22,10 @@ The second syntax (<msg> `HEAD` <commit>...) is supported for
 historical reasons.  Do not use it from the command line or in
 new scripts.  It is the same as `git merge -m <msg> <commit>...`.
 
+*Warning*: Running 'git-merge' with uncommitted changes is
+discouraged: while possible, it leaves you in a state that is hard to
+back out of in the case of a conflict.
+
 
 OPTIONS
 -------
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index b932011..b3fa312 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -24,6 +24,10 @@ when merging local branches into the current branch.
 Also note that options meant for 'git-pull' itself and underlying
 'git-merge' must be given before the options meant for 'git-fetch'.
 
+*Warning*: Running 'git-pull' (actually, the underlying 'git-merge')
+with uncommitted changes is discouraged: while possible, it leaves you
+in a state that is hard to back out of in the case of a conflict.
+
 OPTIONS
 -------
 
-- 
1.6.6.202.gdf32a

[NON-PATCH 3/2] Documentation/git-merge: format full commands in typewriter font

[Thomas Rast]

Use `code snippet` style instead of 'emphasis' for the full commands
specified in the "how to resolve conflicts" section.

Signed-off-by: Thomas Rast <trast@student.ethz.ch>
---

Not intended for application, but for discussion.

I originally wanted to tack this on the series as an "obvious
cleanup", but then I noticed two things:

* While the general trend as per

    git grep '`git '
    git grep \''git '

  seems to go towards the `code` style where full commands are
  concerned, and the 'emphasis' where only a git-command is named,
  this is not consistent yet.  Especially the git-svn manpage seems to
  have a few hybrids.

* More importantly, while `code` style seems to be an improvement in
  HTML output (because it gives typewriter font), my local 'man'
  renders 'emphasis' as underlines -- which actually makes the code
  snippets much more visible than `literal` quotes which are not
  rendered specially at all.

So which way should it be changed?


 Documentation/git-merge.txt |   14 +++++++-------
 1 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index b224daf..e04c800 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -193,7 +193,7 @@ After seeing a conflict, you can do two things:
 
  * Decide not to merge.  The only clean-ups you need are to reset
    the index file to the `HEAD` commit to reverse 2. and to clean
-   up working tree changes made by 2. and 3.; 'git-reset --hard' can
+   up working tree changes made by 2. and 3.; `git-reset --hard` can
    be used for this.
 
  * Resolve the conflicts.  Git will mark the conflicts in
@@ -202,19 +202,19 @@ After seeing a conflict, you can do two things:
 
 You can work through the conflict with a number of tools:
 
- * Use a mergetool.  'git mergetool' to launch a graphical
+ * Use a mergetool.  `git mergetool` to launch a graphical
    mergetool which will work you through the merge.
 
- * Look at the diffs.  'git diff' will show a three-way diff,
+ * Look at the diffs.  `git diff` will show a three-way diff,
    highlighting changes from both the HEAD and 'theirs' versions.
 
- * Look at the diffs on their own. 'git log --merge -p <path>'
+ * Look at the diffs on their own. `git log --merge -p <path>`
    will show diffs first for the HEAD version and then the
    'theirs' version.
 
- * Look at the originals.  'git show :1:filename' shows the
-   common ancestor, 'git show :2:filename' shows the HEAD
-   version and 'git show :3:filename' shows 'their' version.
+ * Look at the originals.  `git show :1:filename` shows the
+   common ancestor, `git show :2:filename` shows the HEAD
+   version and `git show :3:filename` shows 'their' version.
 
 
 EXAMPLES
-- 
1.6.6.202.gdf32a

Re: [PATCH 1/2] Documentation/git-merge: reword references to "remote" and "pull"

[Junio C Hamano]

Thomas Rast <trast@student.ethz.ch> writes:

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

Looks sensible, modulo a few "'theirs' version" that I think should simply
be "their version".

> Out of sheer curiosity:
>
>   The git-merge manpage was written in terms of merging a "remote",
>   which is no longer the case
>
> Was this ever the case?  Or is it just stale terminology?

Somewhere in between stale and lax.  Originally we didn't even have
refs/remotes hierarchy and the distinction between what's local and what's
remote was only in the user's head, and "one branch per repository"
(i.e. you do local clone to work on multiple things, and pull between
them), where even a topic-branch merge is to merge a commit from a remote
(= neighbouring repository of your own), was a more widely practiced
workflow.

Saying <commit> is much more correct than <remote> (technically it can
even be a <committish>, i.e. a tag that peels to a commit).

However...

> @@ -33,10 +33,10 @@ include::merge-options.txt[]
>  	used to give a good default for automated 'git merge'
>  	invocations.
>  
> -<remote>...::
> -	Other branch heads to merge into our branch.  You need at
> -	least one <remote>.  Specifying more than one <remote>
> -	obviously means you are trying an Octopus.
> +<commit>...::
> +	Commits, usually other branch heads, to merge into our branch.
> +	You need at least one <commit>.  Specifying more than one
> +	<commit> obviously means you are trying an Octopus.

I am tempted to suggest describing the command in terms of more common use
pattern, describing the flexible and more general form as "an aside" for
more advanced users, perhaps like this.

        <branch>...:
                Other branch to merge into the current branch...trying an
                Octopus merge.
        +
        Strictly speaking, these can name arbitrary commits, not necessarily
        at the tip of branches.  e.g. "git merge topic{tilde}4" lets you merge
        the topic except for the last 4 commits.

I don't know if such an arrangement really makes the document more
approachable to new people, or it is making the description longer and
more complicated without helping new people, though (that is why this is
just "I am tempted to").

Re: [NON-PATCH 3/2] Documentation/git-merge: format full commands in typewriter font

[Jonathan Nieder]

Thomas Rast wrote:

> * More importantly, while `code` style seems to be an improvement in
>   HTML output (because it gives typewriter font), my local 'man'
>   renders 'emphasis' as underlines -- which actually makes the code
>   snippets much more visible than `literal` quotes which are not
>   rendered specially at all.

Maybe some point in the asciidoc/docbook-xsl/nroff chain could be
convinced to render `literal` quotes underlined on the console.

Jonathan

Re: [NON-PATCH 3/2] Documentation/git-merge: format full commands in typewriter font

[Junio C Hamano]

Thomas Rast <trast@student.ethz.ch> writes:

> * More importantly, while `code` style seems to be an improvement in
>   HTML output (because it gives typewriter font), my local 'man'
>   renders 'emphasis' as underlines -- which actually makes the code
>   snippets much more visible than `literal` quotes which are not
>   rendered specially at all.
>
> So which way should it be changed?

I'd prefer to see us mark code as `code`.

The documentation toolchain may hopefully be fixed in the upstream in the
future, and we could keep our local style tweaks in Documentation/ until
that happens if we really wanted to.

[PATCH v2 0/4] Documentation style fixes

[Thomas Rast]

I'm violating the midnight rule, so there's probably something wrong
with this series.

Junio C Hamano wrote:
> I am tempted to suggest describing the command in terms of more common use
> pattern, describing the flexible and more general form as "an aside" for
> more advanced users, perhaps like this.
> 
>         <branch>...:
>                 Other branch to merge into the current branch...trying an
>                 Octopus merge.
>         +
>         Strictly speaking, these can name arbitrary commits, not necessarily
>         at the tip of branches.  e.g. "git merge topic{tilde}4" lets you merge
>         the topic except for the last 4 commits.
> 
> I don't know if such an arrangement really makes the document more
> approachable to new people, or it is making the description longer and
> more complicated without helping new people, though (that is why this is
> just "I am tempted to").

Not sure.  I have a bit of an aversion against "lying" in the
synopsis, even though the common use-case really is a branch.

> Thomas Rast <trast@student.ethz.ch> writes:
> > * More importantly, while `code` style seems to be an improvement in
> >   HTML output (because it gives typewriter font), my local 'man'
> >   renders 'emphasis' as underlines -- which actually makes the code
> >   snippets much more visible than `literal` quotes which are not
> >   rendered specially at all.
> >
> > So which way should it be changed?
> 
> I'd prefer to see us mark code as `code`.

I tried to make it so, including a few other places that grep found.

Regarding 'git-cmd' vs. 'git cmd', I found that we're in the somewhat
unsatisfactory situation where the git-svn manpage uses dashless since
647ac70 (git-svn.txt: stop using dash-form of commands., 2009-07-07).
Most of the rest uses dashed, but there sometimes even were
inconsistent uses very close to each other.  Dashless seems to be a
bit more common in newer patches, and does have the advantage that it
does not need an exception for 'git submodule update' and friends.

So I tried to sed it towards the dashless form, with a few exceptions.
The churn, of course, is rather daunting.  The other alternative,
returning to dashed forms, would mean reverting 647ac70 and then more
applications of sed to fix the stray dashless uses, being careful to
preserve the SYNOPSIS sections.


Thomas Rast (4):
  Documentation/git-merge: reword references to "remote" and "pull"
  Documentation: warn prominently against merging with dirty trees
  Documentation: format full commands in typewriter font
  Documentation: spell 'git cmd' without dash throughout

 Documentation/config.txt                |   70 +++++++-------
 Documentation/fetch-options.txt         |   10 +-
 Documentation/git-add.txt               |    2 +-
 Documentation/git-am.txt                |   10 +-
 Documentation/git-apply.txt             |   10 +-
 Documentation/git-archimport.txt        |   12 ++--
 Documentation/git-archive.txt           |    2 +-
 Documentation/git-bisect.txt            |    2 +-
 Documentation/git-blame.txt             |    8 +-
 Documentation/git-branch.txt            |    6 +-
 Documentation/git-bundle.txt            |   26 +++---
 Documentation/git-check-ref-format.txt  |    2 +-
 Documentation/git-checkout-index.txt    |    8 +-
 Documentation/git-cherry-pick.txt       |    2 +-
 Documentation/git-cherry.txt            |    6 +-
 Documentation/git-citool.txt            |    4 +-
 Documentation/git-clean.txt             |    4 +-
 Documentation/git-commit-tree.txt       |    2 +-
 Documentation/git-commit.txt            |   18 ++--
 Documentation/git-config.txt            |   14 ++--
 Documentation/git-cvsexportcommit.txt   |    2 +-
 Documentation/git-cvsimport.txt         |   18 ++--
 Documentation/git-cvsserver.txt         |    6 +-
 Documentation/git-daemon.txt            |   40 ++++----
 Documentation/git-describe.txt          |    6 +-
 Documentation/git-diff-files.txt        |    2 +-
 Documentation/git-diff-index.txt        |   16 ++--
 Documentation/git-diff-tree.txt         |    4 +-
 Documentation/git-difftool.txt          |   16 ++--
 Documentation/git-fast-export.txt       |   12 ++--
 Documentation/git-fast-import.txt       |   20 ++--
 Documentation/git-fetch-pack.txt        |    6 +-
 Documentation/git-fetch.txt             |    2 +-
 Documentation/git-filter-branch.txt     |   24 +++---
 Documentation/git-fmt-merge-msg.txt     |    2 +-
 Documentation/git-format-patch.txt      |    4 +-
 Documentation/git-fsck.txt              |    4 +-
 Documentation/git-gc.txt                |   18 ++--
 Documentation/git-get-tar-commit-id.txt |    4 +-
 Documentation/git-grep.txt              |    2 +-
 Documentation/git-gui.txt               |   20 ++--
 Documentation/git-hash-object.txt       |    2 +-
 Documentation/git-help.txt              |    6 +-
 Documentation/git-http-backend.txt      |   22 +++---
 Documentation/git-http-fetch.txt        |    2 +-
 Documentation/git-imap-send.txt         |    2 +-
 Documentation/git-index-pack.txt        |    8 +-
 Documentation/git-init.txt              |    6 +-
 Documentation/git-log.txt               |    2 +-
 Documentation/git-ls-files.txt          |    4 +-
 Documentation/git-ls-tree.txt           |    4 +-
 Documentation/git-mailinfo.txt          |    2 +-
 Documentation/git-merge-file.txt        |   10 +-
 Documentation/git-merge-index.txt       |    6 +-
 Documentation/git-merge-one-file.txt    |    2 +-
 Documentation/git-merge.txt             |   54 ++++++-----
 Documentation/git-mergetool.txt         |   16 ++--
 Documentation/git-name-rev.txt          |    4 +-
 Documentation/git-notes.txt             |    2 +-
 Documentation/git-pack-objects.txt      |    6 +-
 Documentation/git-pack-redundant.txt    |    2 +-
 Documentation/git-patch-id.txt          |    2 +-
 Documentation/git-peek-remote.txt       |    2 +-
 Documentation/git-prune.txt             |   14 ++--
 Documentation/git-pull.txt              |   14 ++-
 Documentation/git-push.txt              |    6 +-
 Documentation/git-read-tree.txt         |   40 ++++----
 Documentation/git-rebase.txt            |   38 ++++----
 Documentation/git-receive-pack.txt      |    6 +-
 Documentation/git-reflog.txt            |    2 +-
 Documentation/git-remote.txt            |    2 +-
 Documentation/git-repack.txt            |   10 +-
 Documentation/git-replace.txt           |    2 +-
 Documentation/git-rerere.txt            |   26 +++---
 Documentation/git-reset.txt             |    2 +-
 Documentation/git-rev-list.txt          |    6 +-
 Documentation/git-rev-parse.txt         |   30 +++---
 Documentation/git-revert.txt            |    8 +-
 Documentation/git-send-pack.txt         |    4 +-
 Documentation/git-sh-setup.txt          |    2 +-
 Documentation/git-shortlog.txt          |    4 +-
 Documentation/git-show-index.txt        |    2 +-
 Documentation/git-show-ref.txt          |    4 +-
 Documentation/git-show.txt              |    4 +-
 Documentation/git-stash.txt             |    8 +-
 Documentation/git-status.txt            |    2 +-
 Documentation/git-submodule.txt         |    8 +-
 Documentation/git-symbolic-ref.txt      |    2 +-
 Documentation/git-tag.txt               |    6 +-
 Documentation/git-tar-tree.txt          |    4 +-
 Documentation/git-update-index.txt      |   14 ++--
 Documentation/git-upload-archive.txt    |    2 +-
 Documentation/git-upload-pack.txt       |    8 +-
 Documentation/git-var.txt               |    2 +-
 Documentation/git-verify-pack.txt       |    2 +-
 Documentation/git-verify-tag.txt        |    2 +-
 Documentation/git-web--browse.txt       |    2 +-
 Documentation/git-whatchanged.txt       |    4 +-
 Documentation/git-write-tree.txt        |    8 +-
 Documentation/git.txt                   |    8 +-
 Documentation/gitattributes.txt         |   12 ++--
 Documentation/gitcore-tutorial.txt      |  148 +++++++++++++++---------------
 Documentation/gitcvs-migration.txt      |   10 +-
 Documentation/gitdiffcore.txt           |    8 +-
 Documentation/githooks.txt              |   56 ++++++------
 Documentation/gitignore.txt             |    4 +-
 Documentation/gitk.txt                  |    2 +-
 Documentation/gitrepository-layout.txt  |   16 ++--
 Documentation/gittutorial-2.txt         |   16 ++--
 Documentation/gittutorial.txt           |   42 +++++-----
 Documentation/gitworkflows.txt          |    6 +-
 Documentation/i18n.txt                  |    4 +-
 Documentation/merge-options.txt         |    4 +-
 Documentation/pull-fetch-param.txt      |    8 +-
 Documentation/urls-remotes.txt          |    4 +-
 115 files changed, 634 insertions(+), 626 deletions(-)

[PATCH v2 1/4] Documentation/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 <trast@student.ethz.ch>
---
 Documentation/git-merge.txt |   34 +++++++++++++++++-----------------
 1 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index e886c2e..4896587 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -10,17 +10,17 @@ SYNOPSIS
 --------
 [verse]
 'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]...
-	[-m <msg>] <remote>...
-'git merge' <msg> HEAD <remote>...
+	[-m <msg>] <commit>...
+'git merge' <msg> HEAD <commit>...
 
 DESCRIPTION
 -----------
-This is the top-level interface to the merge machinery
-which drives multiple merge strategy scripts.
+Merges the history specified by <commit> into HEAD, optionally using a
+specific merge strategy.
 
-The second syntax (<msg> `HEAD` <remote>) is supported for
+The second syntax (<msg> `HEAD` <commit>...) is supported for
 historical reasons.  Do not use it from the command line or in
-new scripts.  It is the same as `git merge -m <msg> <remote>`.
+new scripts.  It is the same as `git merge -m <msg> <commit>...`.
 
 
 OPTIONS
@@ -33,10 +33,10 @@ include::merge-options.txt[]
 	used to give a good default for automated 'git merge'
 	invocations.
 
-<remote>...::
-	Other branch heads to merge into our branch.  You need at
-	least one <remote>.  Specifying more than one <remote>
-	obviously means you are trying an Octopus.
+<commit>...::
+	Commits, usually other branch heads, to merge into our branch.
+	You need at least one <commit>.  Specifying more than one
+	<commit> obviously means you are trying an Octopus.
 
 include::merge-strategies.txt[]
 
@@ -96,8 +96,8 @@ file matches exactly the current `HEAD` commit; otherwise we
 will write out your local changes already registered in your
 index file along with the merge result, which is not good.
 Because 1. involves only those paths differing between your
-branch and the remote branch you are pulling from during the
-merge (which is typically a fraction of the whole tree), you can
+branch and the branch you are merging
+(which is typically a fraction of the whole tree), you can
 have local modifications in your working tree as long as they do
 not overlap with what the merge updates.
 
@@ -110,7 +110,7 @@ When there are conflicts, the following happens:
 
 3. For conflicting paths, the index file records up to three
    versions; stage1 stores the version from the common ancestor,
-   stage2 from `HEAD`, and stage3 from the remote branch (you
+   stage2 from `HEAD`, and stage3 from the other branch (you
    can inspect the stages with `git ls-files -u`).  The working
    tree files contain the result of the "merge" program; i.e. 3-way
    merge results with familiar conflict markers `<<< === >>>`.
@@ -202,15 +202,15 @@ You can work through the conflict with a number of tools:
    mergetool which will work you through the merge.
 
  * Look at the diffs.  'git diff' will show a three-way diff,
-   highlighting changes from both the HEAD and remote versions.
+   highlighting changes from both the HEAD and their versions.
 
  * Look at the diffs on their own. 'git log --merge -p <path>'
-   will show diffs first for the HEAD version and then the
-   remote version.
+   will show diffs first for the HEAD version and then
+   their version.
 
  * Look at the originals.  'git show :1:filename' shows the
    common ancestor, 'git show :2:filename' shows the HEAD
-   version and 'git show :3:filename' shows the remote version.
+   version and 'git show :3:filename' shows their version.
 
 
 EXAMPLES
-- 
1.6.6.218.g502b0

[PATCH v2 2/4] Documentation: warn prominently against merging with dirty trees

[Thomas 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 <trast@student.ethz.ch>
---
 Documentation/git-merge.txt |    4 ++++
 Documentation/git-pull.txt  |    4 ++++
 2 files changed, 8 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 4896587..3277f4e 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -22,6 +22,10 @@ The second syntax (<msg> `HEAD` <commit>...) is supported for
 historical reasons.  Do not use it from the command line or in
 new scripts.  It is the same as `git merge -m <msg> <commit>...`.
 
+*Warning*: Running 'git-merge' with uncommitted changes is
+discouraged: while possible, it leaves you in a state that is hard to
+back out of in the case of a conflict.
+
 
 OPTIONS
 -------
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index b932011..b3fa312 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -24,6 +24,10 @@ when merging local branches into the current branch.
 Also note that options meant for 'git-pull' itself and underlying
 'git-merge' must be given before the options meant for 'git-fetch'.
 
+*Warning*: Running 'git-pull' (actually, the underlying 'git-merge')
+with uncommitted changes is discouraged: while possible, it leaves you
+in a state that is hard to back out of in the case of a conflict.
+
 OPTIONS
 -------
 
-- 
1.6.6.218.g502b0

[PATCH v2 3/4] Documentation: format full commands in typewriter font

[Thomas 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 <trast@student.ethz.ch>
---
 Documentation/config.txt            |   12 ++++++------
 Documentation/git-add.txt           |    2 +-
 Documentation/git-bisect.txt        |    2 +-
 Documentation/git-cvsserver.txt     |    2 +-
 Documentation/git-filter-branch.txt |    6 +++---
 Documentation/git-ls-tree.txt       |    4 ++--
 Documentation/git-merge.txt         |   14 +++++++-------
 Documentation/git-replace.txt       |    2 +-
 Documentation/git-revert.txt        |    4 ++--
 Documentation/git-stash.txt         |    2 +-
 Documentation/git-submodule.txt     |    4 ++--
 Documentation/git-var.txt           |    2 +-
 12 files changed, 28 insertions(+), 28 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 23a965e..6bfd9e1 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -741,15 +741,15 @@ diff.mnemonicprefix::
 	standard "a/" and "b/" depending on what is being compared.  When
 	this configuration is in effect, reverse diff output also swaps
 	the order of the prefixes:
-'git-diff';;
+`git diff`;;
 	compares the (i)ndex and the (w)ork tree;
-'git-diff HEAD';;
+`git diff HEAD`;;
 	 compares a (c)ommit and the (w)ork tree;
-'git diff --cached';;
+`git diff --cached`;;
 	compares a (c)ommit and the (i)ndex;
-'git-diff HEAD:file1 file2';;
+`git-diff HEAD:file1 file2`;;
 	compares an (o)bject and a (w)ork tree entity;
-'git diff --no-index a b';;
+`git diff --no-index a b`;;
 	compares two non-git things (1) and (2).
 
 diff.renameLimit::
@@ -1015,7 +1015,7 @@ gui.spellingdictionary::
 	off.
 
 gui.fastcopyblame::
-	If true, 'git gui blame' uses '-C' instead of '-C -C' for original
+	If true, 'git gui blame' uses `-C` instead of `-C -C` for original
 	location detection. It makes blame significantly faster on huge
 	repositories at the expense of less thorough copy detection.
 
diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 1f1b199..f74fcf3 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -39,7 +39,7 @@ The `git add` command will not add ignored files by default.  If any
 ignored files were explicitly specified on the command line, `git add`
 will fail with a list of ignored files.  Ignored files reached by
 directory recursion or filename globbing performed by Git (quote your
-globs before the shell) will be silently ignored.  The `add` command can
+globs before the shell) will be silently ignored.  The 'git add' command can
 be used to add ignored files with the `-f` (force) option.
 
 Please see linkgit:git-commit[1] for alternative ways to add content to a
diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
index c39d957..f91c7ac 100644
--- a/Documentation/git-bisect.txt
+++ b/Documentation/git-bisect.txt
@@ -26,7 +26,7 @@ on the subcommand:
  git bisect log
  git bisect run <cmd>...
 
-This command uses 'git rev-list --bisect' to help drive the
+This command uses `git rev-list --bisect` to help drive the
 binary search process to find which change introduced a bug, given an
 old "good" commit object name and a later "bad" commit object name.
 
diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt
index 99a7c14..19b1daf 100644
--- a/Documentation/git-cvsserver.txt
+++ b/Documentation/git-cvsserver.txt
@@ -294,7 +294,7 @@ To get a checkout with the Eclipse CVS client:
 Protocol notes: If you are using anonymous access via pserver, just select that.
 Those using SSH access should choose the 'ext' protocol, and configure 'ext'
 access on the Preferences->Team->CVS->ExtConnection pane. Set CVS_SERVER to
-"'git cvsserver'". Note that password support is not good when using 'ext',
+"`git cvsserver`". Note that password support is not good when using 'ext',
 you will definitely want to have SSH keys setup.
 
 Alternatively, you can just use the non-standard extssh protocol that Eclipse
diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index 394a77a..544836a 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -129,8 +129,8 @@ convenience functions, too.  For example, calling 'skip_commit "$@"'
 will leave out the current commit (but not its changes! If you want
 that, use 'git-rebase' instead).
 +
-You can also use the 'git_commit_non_empty_tree "$@"' instead of
-'git commit-tree "$@"' if you don't wish to keep commits with a single parent
+You can also use the `git_commit_non_empty_tree "$@"` instead of
+`git commit-tree "$@"` if you don't wish to keep commits with a single parent
 and that makes no change to the tree.
 
 --tag-name-filter <command>::
@@ -179,7 +179,7 @@ the nearest ancestor that was not excluded.
 	and only one parent, it will hence keep merges points. Also, this
 	option is not compatible with the use of '--commit-filter'. Though you
 	just need to use the function 'git_commit_non_empty_tree "$@"' instead
-	of the 'git commit-tree "$@"' idiom in your commit filter to make that
+	of the `git commit-tree "$@"` idiom in your commit filter to make that
 	happen.
 
 --original <namespace>::
diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
index c3fdccb..1f89d36 100644
--- a/Documentation/git-ls-tree.txt
+++ b/Documentation/git-ls-tree.txt
@@ -28,7 +28,7 @@ in the current working directory.  Note that:
    in a directory 'sub' that has a directory 'dir', you can run 'git
    ls-tree -r HEAD dir' to list the contents of the tree (that is
    'sub/dir' in 'HEAD').  You don't want to give a tree that is not at the
-   root level (e.g. 'git ls-tree -r HEAD:sub dir') in this case, as that
+   root level (e.g. `git ls-tree -r HEAD:sub dir`) in this case, as that
    would result in asking for 'sub/sub/dir' in the 'HEAD' commit.
    However, the current working directory can be ignored by passing
    --full-tree option.
@@ -84,7 +84,7 @@ Output Format
 
 Unless the `-z` option is used, TAB, LF, and backslash characters
 in pathnames are represented as `\t`, `\n`, and `\\`, respectively.
-This output format is compatible with what '--index-info --stdin' of
+This output format is compatible with what `--index-info --stdin` of
 'git update-index' expects.
 
 When the `-l` option is used, format changes to
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 3277f4e..04c21d3 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -193,7 +193,7 @@ After seeing a conflict, you can do two things:
 
  * Decide not to merge.  The only clean-ups you need are to reset
    the index file to the `HEAD` commit to reverse 2. and to clean
-   up working tree changes made by 2. and 3.; 'git-reset --hard' can
+   up working tree changes made by 2. and 3.; `git-reset --hard` can
    be used for this.
 
  * Resolve the conflicts.  Git will mark the conflicts in
@@ -202,19 +202,19 @@ After seeing a conflict, you can do two things:
 
 You can work through the conflict with a number of tools:
 
- * Use a mergetool.  'git mergetool' to launch a graphical
+ * Use a mergetool.  `git mergetool` to launch a graphical
    mergetool which will work you through the merge.
 
- * Look at the diffs.  'git diff' will show a three-way diff,
+ * Look at the diffs.  `git diff` will show a three-way diff,
    highlighting changes from both the HEAD and their versions.
 
- * Look at the diffs on their own. 'git log --merge -p <path>'
+ * Look at the diffs on their own. `git log --merge -p <path>`
    will show diffs first for the HEAD version and then
    their version.
 
- * Look at the originals.  'git show :1:filename' shows the
-   common ancestor, 'git show :2:filename' shows the HEAD
-   version and 'git show :3:filename' shows their version.
+ * Look at the originals.  `git show :1:filename` shows the
+   common ancestor, `git show :2:filename` shows the HEAD
+   version and `git show :3:filename` shows their version.
 
 
 EXAMPLES
diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt
index 65a0da5..fde2092 100644
--- a/Documentation/git-replace.txt
+++ b/Documentation/git-replace.txt
@@ -65,7 +65,7 @@ OPTIONS
 BUGS
 ----
 Comparing blobs or trees that have been replaced with those that
-replace them will not work properly. And using 'git reset --hard' to
+replace them will not work properly. And using `git reset --hard` to
 go back to a replaced commit will move the branch to the replacement
 commit instead of the replaced commit.
 
diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index 5e11758..36f3bc3 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -20,8 +20,8 @@ effect of an earlier commit (often a faulty one).  If you want to
 throw away all uncommitted changes in your working directory, you
 should see linkgit:git-reset[1], particularly the '--hard' option.  If
 you want to extract specific files as they were in another commit, you
-should see linkgit:git-checkout[1], specifically the 'git checkout
-<commit> -- <filename>' syntax.  Take care with these alternatives as
+should see linkgit:git-checkout[1], specifically the `git checkout
+<commit> -- <filename>` syntax.  Take care with these alternatives as
 both will discard uncommitted changes in your working directory.
 
 OPTIONS
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 3f14b72..f001d0e 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -20,7 +20,7 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Use 'git stash' when you want to record the current state of the
+Use `git stash` when you want to record the current state of the
 working directory and the index, but want to go back to a clean
 working directory.  The command saves your local modifications away
 and reverts the working directory to match the `HEAD` commit.
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 4ef70c4..68f656c 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -114,8 +114,8 @@ init::
 	The key used in .git/config is `submodule.$name.url`.
 	This command does not alter existing information in .git/config.
 	You can then customize the submodule clone URLs in .git/config
-	for your local setup and proceed to 'git submodule update';
-	you can also just use 'git submodule update --init' without
+	for your local setup and proceed to `git submodule update`;
+	you can also just use `git submodule update --init` without
 	the explicit 'init' step if you do not intend to customize
 	any submodule locations.
 
diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt
index ef6aa81..bb98182 100644
--- a/Documentation/git-var.txt
+++ b/Documentation/git-var.txt
@@ -20,7 +20,7 @@ OPTIONS
 	Cause the logical variables to be listed. In addition, all the
 	variables of the git configuration file .git/config are listed
 	as well. (However, the configuration variables listing functionality
-	is deprecated in favor of 'git config -l'.)
+	is deprecated in favor of `git config -l`.)
 
 EXAMPLE
 --------
-- 
1.6.6.218.g502b0

Re: [PATCH v2 0/4] Documentation style fixes

[Thomas Rast]

Thomas Rast wrote:
>   Documentation: spell 'git cmd' without dash throughout
[...]
>  115 files changed, 634 insertions(+), 626 deletions(-)

Turns out the fourth patch is over 200kB and can't be sent over the
list.  I pushed the whole series to

  git://repo.or.cz/git/sbeyer.git t/doc-merge-revamp

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

Re: [PATCH v2 0/4] Documentation style fixes

[Thomas Rast]

Thomas Rast wrote:
> Thomas Rast wrote:
> >   Documentation: spell 'git cmd' without dash throughout
> [...]
> >  115 files changed, 634 insertions(+), 626 deletions(-)
> 
> Turns out the fourth patch is over 200kB and can't be sent over the
> list.  I pushed the whole series to
> 
>   git://repo.or.cz/git/sbeyer.git t/doc-merge-revamp

Ah, here's the midnight issue.  That should have said

  git://repo.or.cz/git/trast.git t/doc-merge-revamp

Sorry for the noise.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

Re: [PATCH v2 4/4] Documentation: spell 'git cmd' without dash throughout

[Jonathan Nieder]

Thomas Rast wrote:

> 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.

Agreed.  Some forms of 'man' even support 'man git am', so the "it's
what you pass to 'man'" excuse does not even apply any more.

>  110 files changed, 584 insertions(+), 584 deletions(-)

But yikes!  Did you do this by hand or by some automated process?

> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 6bfd9e1..db28408 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -64,7 +64,7 @@ The values following the equals sign in variable assign are all either
>  a string, an integer, or a boolean.  Boolean values may be given as yes/no,
>  0/1, true/false or on/off.  Case is not significant in boolean values, when
>  converting value to the canonical form using '--bool' type specifier;
> -'git-config' will ensure that the output is "true" or "false".
> +'git config' will ensure that the output is "true" or "false".
>  
>  String values may be entirely or partially enclosed in double quotes.
>  You need to enclose variable values in double quotes if you want to
> @@ -442,7 +442,7 @@ core.pager::
>  
>  core.whitespace::
>  	A comma separated list of common whitespace problems to
> -	notice.  'git-diff' will use `color.diff.whitespace` to
> +	notice.  'git diff' will use `color.diff.whitespace` to
>  	highlight them, and 'git-apply --whitespace=error' will

A 'git-apply' snuck in. ;-)

> @@ -563,24 +563,24 @@ branch.autosetuprebase::
[...]
>  	Specify multiple values to get an octopus merge.
> -	If you wish to setup 'git-pull' so that it merges into <name> from
> +	If you wish to setup 'git pull' so that it merges into <name> from

Not relevant to this patch, but shouldn't ‘setup’ be ‘set up’?

> @@ -718,14 +718,14 @@ commit.template::
>  	specified user's home directory.
>  
>  diff.autorefreshindex::
> -	When using 'git-diff' to compare with work tree
> +	When using 'git diff' to compare with work tree
>  	files, do not consider stat-only change as changed.
>  	Instead, silently run `git update-index --refresh` to
>  	update the cached stat information for paths whose
>  	contents in the work tree match the contents in the
>  	index.  This option defaults to true.  Note that this
> -	affects only 'git-diff' Porcelain, and not lower level
> -	'diff' commands, such as 'git-diff-files'.
> +	affects only 'git diff' Porcelain, and not lower level
> +	'diff' commands, such as 'git diff-files'.

This sounds better to me without the comma before ‘such as’.

> @@ -840,7 +840,7 @@ format.pretty::
>  	linkgit:git-whatchanged[1].
>  
>  format.thread::
> -	The default threading style for 'git-format-patch'.  Can be
> +	The default threading style for 'git format-patch'.  Can be
>  	either a boolean value, `shallow` or `deep`.  `shallow`
>  	threading makes every mail a reply to the head of the series,
>  	where the head is chosen from the cover letter, the

The ‘either’ here sounds awkward, because there are three options.
Also it is not completely clear that ‘shallow’ and ‘deep’ are not
boolean values here.  So maybe ‘Can be a boolean value, or shallow or
deep’, despite the awkward nested ‘or’ expression.

> @@ -875,18 +875,18 @@ gc.autopacklimit::
>  	default	value is 50.  Setting this to 0 disables it.
>  
>  gc.packrefs::
> -	'git-gc' does not run `git pack-refs` in a bare repository by
> +	'git gc' does not run `git pack-refs` in a bare repository by
>  	default so that older dumb-transport clients can still fetch
> -	from the repository.  Setting this to `true` lets 'git-gc'
> +	from the repository.  Setting this to `true` lets 'git gc'
>  	to run `git pack-refs`.  Setting this to `false` tells

Should be ‘lets git gc run’ or ‘tells git gc to run’.  Not to mention
this is not true any more: 'git gc' has run pack-refs by default ever
since commit 56752391 (Make "git gc" pack all refs by default,
2007-05-24).  As that commit message mentions, git versions before
v1.5.1.2 cannot clone repos with packed refs over http, and git
versions before v1.4.4 cannot handled packed refs period, but more
recent git should have no problems.

So to summarize, the changes to config.txt look good, except a
‘git-apply’ snuck past.

The other changes mentioned above follow.

  Documentation: config: git gc packs refs by default now
  Documentation: tiny git config manual tweaks

 Documentation/config.txt |   23 ++++++++++-------------
 1 files changed, 10 insertions(+), 13 deletions(-)

[PATCH 1/2] Documentation: git gc packs refs by default now

[Jonathan Nieder]

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 fe2128a (Change git-gc documentation to reflect
gc.packrefs implementation., 2008-01-09).

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/config.txt |   15 ++++++---------
 1 files changed, 6 insertions(+), 9 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index b5b27ba..bcfed1c 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -875,15 +875,12 @@ gc.autopacklimit::
 	default	value is 50.  Setting this to 0 disables it.
 
 gc.packrefs::
-	'git-gc' does not run `git pack-refs` in a bare repository by
-	default so that older dumb-transport clients can still fetch
-	from the repository.  Setting this to `true` lets 'git-gc'
-	to run `git pack-refs`.  Setting this to `false` tells
-	'git-gc' never to run `git pack-refs`. The default setting is
-	`notbare`. Enable it only when you know you do not have to
-	support such clients.  The default setting will change to `true`
-	at some stage, and setting this to `false` will continue to
-	prevent `git pack-refs` from being run from 'git-gc'.
+	Running `git pack-refs` in a repository renders it
+	unclonable by Git versions prior to 1.5.1.2 over dumb
+	transports such as HTTP.  This variable determines whether
+	'git gc' runs `git pack-refs`. This can be set to "nobare"
+	to enable it within all non-bare repos or it can be set to a
+	boolean value.  The default is `true`.
 
 gc.pruneexpire::
 	When 'git-gc' is run, it will call 'prune --expire 2.weeks.ago'.
-- 
1.6.6

[PATCH 2/2] Documentation: tiny git config manual tweaks

[Jonathan Nieder]

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: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/config.txt |    8 ++++----
 1 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index bcfed1c..f7728ec 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -537,7 +537,7 @@ apply.whitespace::
 	as the '--whitespace' option. See linkgit:git-apply[1].
 
 branch.autosetupmerge::
-	Tells 'git-branch' and 'git-checkout' to setup new branches
+	Tells 'git-branch' and 'git-checkout' to set up new branches
 	so that linkgit:git-pull[1] will appropriately merge from the
 	starting point branch. Note that even if this option is not set,
 	this behavior can be chosen per-branch using the `--track`
@@ -725,7 +725,7 @@ diff.autorefreshindex::
 	contents in the work tree match the contents in the
 	index.  This option defaults to true.  Note that this
 	affects only 'git-diff' Porcelain, and not lower level
-	'diff' commands, such as 'git-diff-files'.
+	'diff' commands such as 'git-diff-files'.
 
 diff.external::
 	If this config variable is set, diff generation is not
@@ -841,8 +841,8 @@ format.pretty::
 
 format.thread::
 	The default threading style for 'git-format-patch'.  Can be
-	either a boolean value, `shallow` or `deep`.  `shallow`
-	threading makes every mail a reply to the head of the series,
+	a boolean value, or `shallow` or `deep`.  `shallow` threading
+	makes every mail a reply to the head of the series,
 	where the head is chosen from the cover letter, the
 	`\--in-reply-to`, and the first patch mail, in this order.
 	`deep` threading makes every mail a reply to the previous one.
-- 
1.6.6

Re: [PATCH v2 3/4] Documentation: format full commands in typewriter font

[Jonathan Nieder]

Thomas Rast wrote:
> * 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'.

Okay.  I think I was guilty of pushing this convention (in commits
like 2fd02c92).  If the distinction is too hazy to be useful, I think
it would be fine to always use `code`, though that would be a bigger
patch.

> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 23a965e..6bfd9e1 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -741,15 +741,15 @@ diff.mnemonicprefix::
>  	standard "a/" and "b/" depending on what is being compared.  When
>  	this configuration is in effect, reverse diff output also swaps
>  	the order of the prefixes:
> -'git-diff';;
> +`git diff`;;
>  	compares the (i)ndex and the (w)ork tree;
> -'git-diff HEAD';;
> +`git diff HEAD`;;
>  	 compares a (c)ommit and the (w)ork tree;
> -'git diff --cached';;
> +`git diff --cached`;;
>  	compares a (c)ommit and the (i)ndex;
> -'git-diff HEAD:file1 file2';;
> +`git-diff HEAD:file1 file2`;;

Shouldn't this use ‘git diff’ (no hyphen)?  Alternatively, if you are
leaving this for the next commit, should the other 'git-diff' lines
keep their dash until then, too?

> diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
> index c39d957..f91c7ac 100644
> --- a/Documentation/git-bisect.txt
> +++ b/Documentation/git-bisect.txt
> @@ -26,7 +26,7 @@ on the subcommand:
>   git bisect log
>   git bisect run <cmd>...
>  
> -This command uses 'git rev-list --bisect' to help drive the
> +This command uses `git rev-list --bisect` to help drive the

Does rev-list --bisect take more arguments (i.e., isn’t the command
being only loosely referred to here)?

> diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
> index 394a77a..544836a 100644
> --- a/Documentation/git-filter-branch.txt
> +++ b/Documentation/git-filter-branch.txt
> @@ -129,8 +129,8 @@ convenience functions, too.  For example, calling 'skip_commit "$@"'
>  will leave out the current commit (but not its changes! If you want
>  that, use 'git-rebase' instead).
>  +
> -You can also use the 'git_commit_non_empty_tree "$@"' instead of
> -'git commit-tree "$@"' if you don't wish to keep commits with a single parent
> +You can also use the `git_commit_non_empty_tree "$@"` instead of
> +`git commit-tree "$@"` if you don't wish to keep commits with a single parent
>  and that makes no change to the tree.

Not this commit’s topic, but perhaps ‘use the ...’ should be ‘use ...’
or ‘use the ... idiom’...

>  --tag-name-filter <command>::
> @@ -179,7 +179,7 @@ the nearest ancestor that was not excluded.
>  	and only one parent, it will hence keep merges points. Also, this
>  	option is not compatible with the use of '--commit-filter'. Though you
>  	just need to use the function 'git_commit_non_empty_tree "$@"' instead
> -	of the 'git commit-tree "$@"' idiom in your commit filter to make that
> +	of the `git commit-tree "$@"` idiom in your commit filter to make that
>  	happen.

... to match this.

> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> index 3277f4e..04c21d3 100644
> --- a/Documentation/git-merge.txt
> +++ b/Documentation/git-merge.txt
> @@ -193,7 +193,7 @@ After seeing a conflict, you can do two things:
>  
>   * Decide not to merge.  The only clean-ups you need are to reset
>     the index file to the `HEAD` commit to reverse 2. and to clean
> -   up working tree changes made by 2. and 3.; 'git-reset --hard' can
> +   up working tree changes made by 2. and 3.; `git-reset --hard` can

Probably `git reset --hard` (I won’t mention any more of these).

Except for the bisect-change above,
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>

The rest looks good, and really does seem clearer in some places.

Thanks,
Jonathan

Re: [PATCH v2 1/4] Documentation/git-merge: reword references to "remote" and "pull"

[Jonathan Nieder]

Thomas Rast wrote:
> 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.
 
Right.

> 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).

Makes sense.  It might be nice to emphasize the metaphor of merging
another branch’s history into the current branch, but <commit>
really does seem clearer than ‘{ <branch> | <commit> }’ or any other
alternative I can come up with.

> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> index e886c2e..4896587 100644
> --- a/Documentation/git-merge.txt
> +++ b/Documentation/git-merge.txt
> @@ -10,17 +10,17 @@ SYNOPSIS
>  --------
>  [verse]
>  'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]...
> -	[-m <msg>] <remote>...
> -'git merge' <msg> HEAD <remote>...
> +	[-m <msg>] <commit>...
> +'git merge' <msg> HEAD <commit>...
>  
>  DESCRIPTION
>  -----------
> -This is the top-level interface to the merge machinery
> -which drives multiple merge strategy scripts.
> +Merges the history specified by <commit> into HEAD, optionally using a
> +specific merge strategy.

Perhaps just

| Rejoins two or more diverging branches of development.

would be simpler.  The ability to choose a merge strategy seems more
like a detail for later.

> -The second syntax (<msg> `HEAD` <remote>) is supported for
> +The second syntax (<msg> `HEAD` <commit>...) is supported for
>  historical reasons.  Do not use it from the command line or in
> -new scripts.  It is the same as `git merge -m <msg> <remote>`.
> +new scripts.  It is the same as `git merge -m <msg> <commit>...`.

Technically, they are not entirely the same: ‘merge -m <msg>’ will
warn that the log message is ignored when the merge results in a
fast-forward, whereas ‘merge <msg> HEAD’ will not.  See commit
77c29b4a (Revert recent "git merge <msg> HEAD <commit>..."
deprecation, 2009-12-08).  So should this say

| Use `git merge -m <msg> <commit>...` instead.

to side-step the issue?  Not sure.

> @@ -33,10 +33,10 @@ include::merge-options.txt[]
>  	used to give a good default for automated 'git merge'
>  	invocations.
>  
> -<remote>...::
> -	Other branch heads to merge into our branch.  You need at
> -	least one <remote>.  Specifying more than one <remote>
> -	obviously means you are trying an Octopus.
> +<commit>...::
> +	Commits, usually other branch heads, to merge into our branch.
> +	You need at least one <commit>.  Specifying more than one
> +	<commit> obviously means you are trying an Octopus.

Nice.

> @@ -96,8 +96,8 @@ file matches exactly the current `HEAD` commit; otherwise we
>  will write out your local changes already registered in your
>  index file along with the merge result, which is not good.
>  Because 1. involves only those paths differing between your
> -branch and the remote branch you are pulling from during the
> -merge (which is typically a fraction of the whole tree), you can
> +branch and the branch you are merging
> +(which is typically a fraction of the whole tree), you can

Hmm.  The old wording distinguishes nicely between the HEAD and
MERGE_HEAD that will be parents for the new HEAD.  From some points
of view, the new wording does not: both are branches you are
merging (though only one is an argument to 'git merge').

Sadly, I have not come up with a good expression for “the other
commit whose history is to be incorporated into the current
branch”.

Maybe we should punt and just say “the other branch”?

> @@ -202,15 +202,15 @@ You can work through the conflict with a number of tools:
>     mergetool which will work you through the merge.
>  
>   * Look at the diffs.  'git diff' will show a three-way diff,
> -   highlighting changes from both the HEAD and remote versions.
> +   highlighting changes from both the HEAD and their versions.
>  
>   * Look at the diffs on their own. 'git log --merge -p <path>'

This is a bit awkward, since 'they' is playing two roles.  Also,
the context does not make it obvious what 'our' and 'their'
versions are.

Maybe:

|   * Look at the diffs.  'git diff' will show a three-way diff,
|     highlighting changes from both the HEAD and MERGE_HEAD
|     versions.
|
|   * Look at the diffs from each branch.  'git log --merge -p
|     <path>' will show diffs first for the HEAD version and
|     then the MERGE_HEAD version.
|
|   * Look at the originals.  'git show :1:filename' shows the
|     common ancestor, 'git show :2:filename' shows the HEAD
|     version, and 'git show :3:filename' shows the MERGE_HEAD
|     version.

Thanks for looking into this,
Jonathan

Re: [PATCH v2 2/4] Documentation: warn prominently against merging with dirty trees

[Jonathan Nieder]

Thomas Rast wrote:

> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> index 4896587..3277f4e 100644
> --- a/Documentation/git-merge.txt
> +++ b/Documentation/git-merge.txt
> @@ -22,6 +22,10 @@ The second syntax (<msg> `HEAD` <commit>...) is supported for
>  historical reasons.  Do not use it from the command line or in
>  new scripts.  It is the same as `git merge -m <msg> <commit>...`.
>  
> +*Warning*: Running 'git-merge' with uncommitted changes is
> +discouraged:

Is this true?  The 'git reset' manual page gives an example of something
I end up doing pretty often:

| Undo a merge or pull inside a dirty work tree
|
|         $ git pull                         (1)
|         Auto-merging nitfol
|         Merge made by recursive.
|          nitfol                |   20 +++++----
|          ...
|         $ git reset --merge ORIG_HEAD      (2)
|
|     1. Even if you may have local modifications in your working tree, you
|     can safely say "git pull" when you know that the change in the other
|     branch does not overlap with them.
|     2. After inspecting the result of the merge, you may find that the
|     change in the other branch is unsatisfactory. Running "git reset
|     --hard ORIG_HEAD" will let you go back to where you were, but it will
|     discard your local changes, which you do not want. "git reset --merge"
|     keeps your local changes.

> while possible, it leaves you in a state that is hard to
> +back out of in the case of a conflict.
> +

Oh, that is a problem.  Maybe 'git merge' should refuse to merge
unless told otherwise, if there is a dirty index and there might be
conflicts.

In other words, would it be possible to fix this without relying on
people to look at the documentation?

Jonathan

Re: [PATCH v2 2/4] Documentation: warn prominently against merging with dirty trees

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> |     1. Even if you may have local modifications in your working tree, you
> |     can safely say "git pull" when you know that the change in the other
> |     branch does not overlap with them.
> |     2. After inspecting the result of the merge, you may find that the
> |     change in the other branch is unsatisfactory. Running "git reset
> |     --hard ORIG_HEAD" will let you go back to where you were, but it will
> |     discard your local changes, which you do not want. "git reset --merge"
> |     keeps your local changes.
>
>> while possible, it leaves you in a state that is hard to
>> +back out of in the case of a conflict.
>> +
>
> Oh, that is a problem.  Maybe 'git merge' should refuse to merge
> unless told otherwise, if there is a dirty index and there might be
> conflicts.

"git reset --merge" will keep your local changes after such a merge, and
"mergy" operations (not just "merge" but also "revert", "am -3", etc)
won't get you into a situation where you cannot, by refusing to do
anything when e.g. your index is dirty.  Especially when Christian's
"reset --merge" update becomes solid, "... is hard to back out of" will
become a false statement.

Of course, the user needs to understand what he or she is doing (see
http://thread.gmane.org/gmane.comp.version-control.git/136166/focus=136171
for example).  And that is one reason we (at least I) try to teach new
people to start working from a clean tree, until they get comfortable
working with mergy operations.

Re: [PATCH v2 0/4] Documentation style fixes

[Junio C Hamano]

As to the general direction I am in full agreement with what you and
Jonathan discussed in the review of your series, namely:

 - We prefer dashless these days;

 - Reference to a concrete command line is <code>git clone</code> which is
   typeset differently from general descriptions of what <emphasis>git
   clone</emphasis> command does.

I'd like to proceed with this series by (1) pulling from you and queuing
the result in 'next', (2) asking other people (including Jonathan) to
proofread and send necessary updates to the list, (3) asking you to check
and queue these updates from others yourself and tell me to pull again to
my 'next', and (4) merging the result to 'master' when done.

Does it sound workable?  Am I placing too much undue burden on you?

Re: [PATCH v2 0/4] Documentation style fixes

[Junio C Hamano]

Thomas Rast <trast@student.ethz.ch> writes:

> Turns out the fourth patch is over 200kB and can't be sent over the
> list.  I pushed the whole series to
>
>   git://repo.or.cz/git/sbeyer.git t/doc-merge-revamp

I think you meant s/sbeyer/trast/ ;-)

Re: [PATCH v2 0/4] Documentation style fixes

[Thomas Rast]

Junio C Hamano wrote:
> 
> I'd like to proceed with this series by (1) pulling from you and queuing
> the result in 'next', (2) asking other people (including Jonathan) to
> proofread and send necessary updates to the list, (3) asking you to check
> and queue these updates from others yourself and tell me to pull again to
> my 'next', and (4) merging the result to 'master' when done.
> 
> Does it sound workable?  Am I placing too much undue burden on you?

No, that's fine, and indeed I'm glad I'm not putting too much
conflict-resolution burden on you.

I took the not-yet-merged (I hope I understood the above right :-)
liberty of squashing fixes from Jonathan's review.  I'll send the
interdiffs as a reply to this mail.  They're now at

  git://repo.or.cz/git/trast.git doc-style/for-next

(I'm leaving the old head in place for comparison).  I'm gathering
incremental updates in

  git://repo.or.cz/git/trast.git doc-style/pu

For now we have

Jonathan Nieder (2):
      Documentation: git gc packs refs by default now
      Documentation: tiny git config manual tweaks

Thomas Rast (1):
      Documentation: show-files is now called git-ls-files

I'll also send the last one for review shortly, though it's rather
trivial.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

[PATCH 1/2] More missed dashed 'git-cmd' forms

[Thomas Rast]

Squashed into the corresponding commit of the original series.
---
 Documentation/config.txt                |   14 +++++++-------
 Documentation/git-archive.txt           |    2 +-
 Documentation/git-commit.txt            |    2 +-
 Documentation/git-daemon.txt            |    4 ++--
 Documentation/git-diff-index.txt        |    4 ++--
 Documentation/git-diff-tree.txt         |    6 +++---
 Documentation/git-for-each-ref.txt      |    2 +-
 Documentation/git-gc.txt                |    2 +-
 Documentation/git-get-tar-commit-id.txt |    2 +-
 Documentation/git-help.txt              |    2 +-
 Documentation/git-instaweb.txt          |    2 +-
 Documentation/git-log.txt               |    2 +-
 Documentation/git-ls-files.txt          |    2 +-
 Documentation/git-mailinfo.txt          |    2 +-
 Documentation/git-merge-index.txt       |    2 +-
 Documentation/git-merge-one-file.txt    |    4 ++--
 Documentation/git-prune.txt             |    2 +-
 Documentation/git-read-tree.txt         |    2 +-
 Documentation/git-repack.txt            |    2 +-
 Documentation/git-rerere.txt            |    2 +-
 Documentation/git-rev-parse.txt         |    4 ++--
 Documentation/git-show-index.txt        |    2 +-
 Documentation/git-show.txt              |    2 +-
 Documentation/git-tag.txt               |    2 +-
 Documentation/git-tar-tree.txt          |    2 +-
 Documentation/git-update-index.txt      |    8 ++++----
 Documentation/git-upload-archive.txt    |    2 +-
 Documentation/git-web--browse.txt       |    4 ++--
 Documentation/gitcore-tutorial.txt      |   12 ++++++------
 Documentation/gitdiffcore.txt           |   18 +++++++++---------
 Documentation/githooks.txt              |    8 ++++----
 Documentation/gitrepository-layout.txt  |    2 +-
 32 files changed, 64 insertions(+), 64 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 937dfbe..5d549ca 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -443,7 +443,7 @@ core.pager::
 core.whitespace::
 	A comma separated list of common whitespace problems to
 	notice.  'git diff' will use `color.diff.whitespace` to
-	highlight them, and 'git-apply --whitespace=error' will
+	highlight them, and 'git apply --whitespace=error' will
 	consider them as errors.  You can prefix `-` to disable
 	any of them (e.g. `-trailing-space`):
 +
@@ -673,7 +673,7 @@ color.interactive::
 	colors only when the output is to the terminal. Defaults to false.
 
 color.interactive.<slot>::
-	Use customized color for 'git-add --interactive'
+	Use customized color for 'git add --interactive'
 	output. `<slot>` may be `prompt`, `header`, `help` or `error`, for
 	four distinct types of normal output from interactive
 	commands.  The values of these variables may be specified as
@@ -858,7 +858,7 @@ format.signoff::
 
 gc.aggressiveWindow::
 	The window size parameter used in the delta compression
-	algorithm used by 'git-gc --aggressive'.  This defaults
+	algorithm used by 'git gc --aggressive'.  This defaults
 	to 10.
 
 gc.auto::
@@ -889,22 +889,22 @@ gc.pruneexpire::
 	unreachable objects immediately.
 
 gc.reflogexpire::
-	'git-reflog expire' removes reflog entries older than
+	'git reflog expire' removes reflog entries older than
 	this time; defaults to 90 days.
 
 gc.reflogexpireunreachable::
-	'git-reflog expire' removes reflog entries older than
+	'git reflog expire' removes reflog entries older than
 	this time and are not reachable from the current tip;
 	defaults to 30 days.
 
 gc.rerereresolved::
 	Records of conflicted merge you resolved earlier are
-	kept for this many days when 'git-rerere gc' is run.
+	kept for this many days when 'git rerere gc' is run.
 	The default is 60 days.  See linkgit:git-rerere[1].
 
 gc.rerereunresolved::
 	Records of conflicted merge you have not resolved are
-	kept for this many days when 'git-rerere gc' is run.
+	kept for this many days when 'git rerere gc' is run.
 	The default is 15 days.  See linkgit:git-rerere[1].
 
 gitcvs.commitmsgannotation::
diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt
index 980bc62..799c8b6 100644
--- a/Documentation/git-archive.txt
+++ b/Documentation/git-archive.txt
@@ -27,7 +27,7 @@ used as the modification time of each file in the archive.  In the latter
 case the commit time as recorded in the referenced commit object is
 used instead.  Additionally the commit ID is stored in a global
 extended pax header if the tar format is used; it can be extracted
-using 'git-get-tar-commit-id'. In ZIP files it is stored as a file
+using 'git get-tar-commit-id'. In ZIP files it is stored as a file
 comment.
 
 OPTIONS
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 8914543..c322c75 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -40,7 +40,7 @@ The content to be added can be specified in several ways:
 
 5. by using the --interactive switch with the 'commit' command to decide one
    by one which files should be part of the commit, before finalizing the
-   operation.  Currently, this is done by invoking 'git-add --interactive'.
+   operation.  Currently, this is done by invoking 'git add --interactive'.
 
 The `--dry-run` option can be used to obtain a
 summary of what is included by any of the above for the next
diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt
index ece232e..01c9f8e 100644
--- a/Documentation/git-daemon.txt
+++ b/Documentation/git-daemon.txt
@@ -181,7 +181,7 @@ upload-pack::
 	item to `false`.
 
 upload-archive::
-	This serves 'git-archive --remote'.  It is disabled by
+	This serves 'git archive --remote'.  It is disabled by
 	default, but a repository can enable it by setting
 	`daemon.uploadarch` configuration item to `true`.
 
@@ -258,7 +258,7 @@ Repositories can still be accessed by hostname though, assuming
 they correspond to these IP addresses.
 
 selectively enable/disable services per repository::
-	To enable 'git-archive --remote' and disable 'git fetch' against
+	To enable 'git archive --remote' and disable 'git fetch' against
 	a repository, have the following in the configuration file in the
 	repository (that is the file 'config' next to 'HEAD', 'refs' and
 	'objects').
diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt
index 84acf49..162cb74 100644
--- a/Documentation/git-diff-index.txt
+++ b/Documentation/git-diff-index.txt
@@ -72,7 +72,7 @@ In fact, `git diff-index --cached` *should* always be entirely equivalent to
 actually doing a 'git write-tree' and comparing that. Except this one is much
 nicer for the case where you just want to check where you are.
 
-So doing a 'git-diff-index --cached' is basically very useful when you are
+So doing a `git diff-index --cached` is basically very useful when you are
 asking yourself "what have I already marked for being committed, and
 what's the difference to a previous tree".
 
@@ -87,7 +87,7 @@ The non-cached version asks the question:
   tree - index contents _and_ files that aren't up-to-date
 
 which is obviously a very useful question too, since that tells you what
-you *could* commit. Again, the output matches the 'git-diff-tree -r'
+you *could* commit. Again, the output matches the 'git diff-tree -r'
 output to a tee, but with a twist.
 
 The twist is that if some file doesn't match the index, we don't have
diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
index 95c402a..a7e37b8 100644
--- a/Documentation/git-diff-tree.txt
+++ b/Documentation/git-diff-tree.txt
@@ -67,19 +67,19 @@ The following flags further affect the behavior when comparing
 commits (but not trees).
 
 -m::
-	By default, 'git-diff-tree --stdin' does not show
+	By default, 'git diff-tree --stdin' does not show
 	differences for merge commits.  With this flag, it shows
 	differences to that commit from all of its parents. See
 	also '-c'.
 
 -s::
-	By default, 'git-diff-tree --stdin' shows differences,
+	By default, 'git diff-tree --stdin' shows differences,
 	either in machine-readable form (without '-p') or in patch
 	form (with '-p').  This output can be suppressed.  It is
 	only useful with '-v' flag.
 
 -v::
-	This flag causes 'git-diff-tree --stdin' to also show
+	This flag causes 'git diff-tree --stdin' to also show
 	the commit message before the differences.
 
 include::pretty-options.txt[]
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index 8dc873f..7e83288 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -82,7 +82,7 @@ objecttype::
 	The type of the object (`blob`, `tree`, `commit`, `tag`).
 
 objectsize::
-	The size of the object (the same as 'git-cat-file -s' reports).
+	The size of the object (the same as 'git cat-file -s' reports).
 
 objectname::
 	The object name (aka SHA-1).
diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt
index 07f211f..771807f 100644
--- a/Documentation/git-gc.txt
+++ b/Documentation/git-gc.txt
@@ -50,7 +50,7 @@ Housekeeping is required if there are too many loose objects or
 too many packs in the repository. If the number of loose objects
 exceeds the value of the `gc.auto` configuration variable, then
 all loose objects are combined into a single pack using
-'git-repack -d -l'.  Setting the value of `gc.auto` to 0
+'git repack -d -l'.  Setting the value of `gc.auto` to 0
 disables automatic packing of loose objects.
 +
 If the number of packs exceeds the value of `gc.autopacklimit`,
diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt
index 94c434b..790af95 100644
--- a/Documentation/git-get-tar-commit-id.txt
+++ b/Documentation/git-get-tar-commit-id.txt
@@ -17,7 +17,7 @@ Acts as a filter, extracting the commit ID stored in archives created by
 'git archive'.  It reads only the first 1024 bytes of input, thus its
 runtime is not influenced by the size of <tarfile> very much.
 
-If no commit ID is found, 'git-get-tar-commit-id' quietly exists with a
+If no commit ID is found, 'git get-tar-commit-id' quietly exists with a
 return code of 1.  This can happen if <tarfile> had not been created
 using 'git archive' or if the first parameter of 'git archive' had been
 a tree ID instead of a commit ID or tag.
diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index ce41b65..f8df109 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -55,7 +55,7 @@ other display programs (see below).
 +
 The web browser can be specified using the configuration variable
 'help.browser', or 'web.browser' if the former is not set. If none of
-these config variables is set, the 'git-web--browse' helper script
+these config variables is set, the 'git web--browse' helper script
 (called by 'git help') will pick a suitable default. See
 linkgit:git-web--browse[1] for more information about this.
 
diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt
index 0771f25..a1f17df 100644
--- a/Documentation/git-instaweb.txt
+++ b/Documentation/git-instaweb.txt
@@ -44,7 +44,7 @@ OPTIONS
 -b::
 --browser::
 	The web browser that should be used to view the gitweb
-	page. This will be passed to the 'git-web--browse' helper
+	page. This will be passed to the 'git web--browse' helper
 	script along with the URL of the gitweb instance. See
 	linkgit:git-web--browse[1] for more information about this. If
 	the script fails, the URL will be printed to stdout.
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index cb12f09..ff4063b 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -16,7 +16,7 @@ Shows the commit logs.
 
 The command takes options applicable to the 'git rev-list'
 command to control what is shown and how, and options applicable to
-the 'git-diff-*' commands to control how the changes
+the 'git diff-*' commands to control how the changes
 each commit introduces are shown.
 
 
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 92b21d7..7faba23 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -145,7 +145,7 @@ which case it outputs:
 
         [<tag> ]<mode> <object> <stage> <file>
 
-'git-ls-files --unmerged' and 'git-ls-files --stage' can be used to examine
+'git ls-files --unmerged' and 'git ls-files --stage' can be used to examine
 detailed information on unmerged paths.
 
 For an unmerged path, instead of recording a single mode/SHA1 pair,
diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt
index a524252..e3d58cb 100644
--- a/Documentation/git-mailinfo.txt
+++ b/Documentation/git-mailinfo.txt
@@ -30,7 +30,7 @@ OPTIONS
 	whitespaces, (3) '[' up to ']', typically '[PATCH]', and
 	then prepends "[PATCH] ".  This flag forbids this
 	munging, and is most useful when used to read back
-	'git-format-patch -k' output.
+	'git format-patch -k' output.
 
 -b::
 	When -k is not in effect, all leading strings bracketed with '['
diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt
index 493f061..4d266de 100644
--- a/Documentation/git-merge-index.txt
+++ b/Documentation/git-merge-index.txt
@@ -43,7 +43,7 @@ code.
 Typically this is run with a script calling git's imitation of
 the 'merge' command from the RCS package.
 
-A sample script called 'git-merge-one-file' is included in the
+A sample script called 'git merge-one-file' is included in the
 distribution.
 
 ALERT ALERT ALERT! The git "merge object order" is different from the
diff --git a/Documentation/git-merge-one-file.txt b/Documentation/git-merge-one-file.txt
index 7360202..a163cfc 100644
--- a/Documentation/git-merge-one-file.txt
+++ b/Documentation/git-merge-one-file.txt
@@ -8,12 +8,12 @@ git-merge-one-file - The standard helper program to use with git-merge-index
 
 SYNOPSIS
 --------
-'git-merge-one-file'
+'git merge-one-file'
 
 DESCRIPTION
 -----------
 This is the standard helper program to use with 'git merge-index'
-to resolve a merge after the trivial merge done with 'git-read-tree -m'.
+to resolve a merge after the trivial merge done with 'git read-tree -m'.
 
 Author
 ------
diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt
index 437d7c4..3bb7304 100644
--- a/Documentation/git-prune.txt
+++ b/Documentation/git-prune.txt
@@ -16,7 +16,7 @@ DESCRIPTION
 NOTE: In most cases, users should run 'git gc', which calls
 'git prune'. See the section "NOTES", below.
 
-This runs 'git-fsck --unreachable' using all the refs
+This runs 'git fsck --unreachable' using all the refs
 available in `$GIT_DIR/refs`, optionally with additional set of
 objects specified on the command line, and prunes all unpacked
 objects unreachable from any of these head objects from the object database.
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index 469cd69..a31a4cb 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -298,7 +298,7 @@ populated.  Here is an outline of how the algorithm works:
     trivial rules ..
 
 You would normally use 'git merge-index' with supplied
-'git-merge-one-file' to do this last step.  The script updates
+'git merge-one-file' to do this last step.  The script updates
 the files in the working tree as it merges each path and at the
 end of a successful merge.
 
diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt
index 50a5c96..538895c 100644
--- a/Documentation/git-repack.txt
+++ b/Documentation/git-repack.txt
@@ -71,7 +71,7 @@ other objects in that pack they already have locally.
 
 -n::
 	Do not update the server information with
-	'git-update-server-info'.  This option skips
+	'git update-server-info'.  This option skips
 	updating local catalog files needed to publish
 	this repository (or a direct copy of it)
 	over HTTP or FTP.  See linkgit:git-update-server-info[1].
diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt
index 8dab467..acc220a 100644
--- a/Documentation/git-rerere.txt
+++ b/Documentation/git-rerere.txt
@@ -37,7 +37,7 @@ its working state.
 'clear'::
 
 This resets the metadata used by rerere if a merge resolution is to be
-aborted.  Calling 'git-am [--skip|--abort]' or 'git-rebase [--skip|--abort]'
+aborted.  Calling 'git am [--skip|--abort]' or 'git rebase [--skip|--abort]'
 will automatically invoke this command.
 
 'diff'::
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index fff4cb8..82ae16e 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -74,7 +74,7 @@ OPTIONS
 	properly quoted for consumption by shell.  Useful when
 	you expect your parameter to contain whitespaces and
 	newlines (e.g. when using pickaxe `-S` with
-	'git-diff-\*'). In contrast to the `--sq-quote` option,
+	'git diff-\*'). In contrast to the `--sq-quote` option,
 	the command input is still interpreted as usual.
 
 --not::
@@ -361,7 +361,7 @@ usage on the standard error stream, and exits with code 129.
 Input Format
 ~~~~~~~~~~~~
 
-'git-rev-parse --parseopt' input format is fully text based. It has two parts,
+'git rev-parse --parseopt' input format is fully text based. It has two parts,
 separated by a line that contains only `--`. The lines before the separator
 (should be more than one) are used for the usage.
 The lines after the separator describe the options.
diff --git a/Documentation/git-show-index.txt b/Documentation/git-show-index.txt
index deebdc8..8382fbe 100644
--- a/Documentation/git-show-index.txt
+++ b/Documentation/git-show-index.txt
@@ -17,7 +17,7 @@ Reads given idx file for packed git archive created with
 'git pack-objects' command, and dumps its contents.
 
 The information it outputs is subset of what you can get from
-'git-verify-pack -v'; this command only shows the packfile
+'git verify-pack -v'; this command only shows the packfile
 offset and SHA1 of each object.
 
 
diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt
index de83d6b..55e687a 100644
--- a/Documentation/git-show.txt
+++ b/Documentation/git-show.txt
@@ -16,7 +16,7 @@ Shows one or more objects (blobs, trees, tags and commits).
 
 For commits it shows the log message and textual diff. It also
 presents the merge commit in a special format as produced by
-'git-diff-tree --cc'.
+'git diff-tree --cc'.
 
 For tags, it shows the tag message and the referenced objects.
 
diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 518bf98..31c78a8 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -131,7 +131,7 @@ and be done with it.
 
 . The insane thing.
 You really want to call the new version "X" too, 'even though'
-others have already seen the old one. So just use 'git-tag -f'
+others have already seen the old one. So just use 'git tag -f'
 again, as if you hadn't already published the old one.
 
 However, Git does *not* (and it should not) change tags behind
diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt
index 7c116ec..3c786bd 100644
--- a/Documentation/git-tar-tree.txt
+++ b/Documentation/git-tar-tree.txt
@@ -24,7 +24,7 @@ a commit ID or tag ID.  In the first case the current time is used as
 modification time of each file in the archive.  In the latter case the
 commit time as recorded in the referenced commit object is used instead.
 Additionally the commit ID is stored in a global extended pax header.
-It can be extracted using 'git-get-tar-commit-id'.
+It can be extracted using 'git get-tar-commit-id'.
 
 OPTIONS
 -------
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index c2477b9..e8c19be 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -206,7 +206,7 @@ into the index file.
     . mode         SP sha1 SP stage TAB path
 +
 This format is to put higher order stages into the
-index file and matches 'git-ls-files --stage' output.
+index file and matches 'git ls-files --stage' output.
 
 To place a higher stage entry to the index, the path should
 first be removed by feeding a mode=0 entry for the path, and
@@ -263,8 +263,8 @@ option.  To unset, use `--no-assume-unchanged`.
 The command looks at `core.ignorestat` configuration variable.  When
 this is true, paths updated with `git update-index paths...` and
 paths updated with other git commands that update both index and
-working tree (e.g. 'git-apply --index', 'git-checkout-index -u',
-and 'git-read-tree -u') are automatically marked as "assume
+working tree (e.g. 'git apply --index', 'git checkout-index -u',
+and 'git read-tree -u') are automatically marked as "assume
 unchanged".  Note that "assume unchanged" bit is *not* set if
 `git update-index --refresh` finds the working tree file matches
 the index (use `git update-index --really-refresh` if you want
@@ -317,7 +317,7 @@ unreliable, this should be set to 'false' (see linkgit:git-config[1]).
 This causes the command to ignore differences in file modes recorded
 in the index and the file mode on the filesystem if they differ only on
 executable bit.   On such an unfortunate filesystem, you may
-need to use 'git-update-index --chmod='.
+need to use 'git update-index --chmod='.
 
 Quite similarly, if `core.symlinks` configuration variable is set
 to 'false' (see linkgit:git-config[1]), symbolic links are checked out
diff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt
index afe6595..f5f2b39 100644
--- a/Documentation/git-upload-archive.txt
+++ b/Documentation/git-upload-archive.txt
@@ -12,7 +12,7 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Invoked by 'git-archive --remote' and sends a generated archive to the
+Invoked by 'git archive --remote' and sends a generated archive to the
 other end over the git protocol.
 
 This command is usually not invoked directly by the end user.  The UI
diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt
index 91a54a6..7572049 100644
--- a/Documentation/git-web--browse.txt
+++ b/Documentation/git-web--browse.txt
@@ -62,7 +62,7 @@ browser.<tool>.path
 You can explicitly provide a full path to your preferred browser by
 setting the configuration variable 'browser.<tool>.path'. For example,
 you can configure the absolute path to firefox by setting
-'browser.firefox.path'. Otherwise, 'git-web--browse' assumes the tool
+'browser.firefox.path'. Otherwise, 'git web--browse' assumes the tool
 is available in PATH.
 
 browser.<tool>.cmd
@@ -71,7 +71,7 @@ browser.<tool>.cmd
 When the browser, specified by options or configuration variables, is
 not among the supported ones, then the corresponding
 'browser.<tool>.cmd' configuration variable will be looked up. If this
-variable exists then 'git-web--browse' will treat the specified tool
+variable exists then 'git web--browse' will treat the specified tool
 as a custom command and will use a shell eval to run the command with
 the URLs passed as arguments.
 
diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt
index 202a379..c005f37 100644
--- a/Documentation/gitcore-tutorial.txt
+++ b/Documentation/gitcore-tutorial.txt
@@ -428,7 +428,7 @@ $ git update-index hello
 (note how we didn't need the `\--add` flag this time, since git knew
 about the file already).
 
-Note what happens to the different 'git-diff-\*' versions here. After
+Note what happens to the different 'git diff-\*' versions here. After
 we've updated `hello` in the index, `git diff-files -p` now shows no
 differences, but `git diff-index -p HEAD` still *does* show that the
 current state is different from the state we committed. In fact, now
@@ -1095,7 +1095,7 @@ The 'commit walkers' are sometimes also called 'dumb
 transports', because they do not require any git aware smart
 server like git Native transport does.  Any stock HTTP server
 that does not even support directory index would suffice.  But
-you must prepare your repository with 'git-update-server-info'
+you must prepare your repository with 'git update-server-info'
 to help dumb transport downloaders.
 
 Once you fetch from the remote repository, you `merge` that
@@ -1260,7 +1260,7 @@ $ git ls-files --unmerged
 
 The next step of merging is to merge these three versions of the
 file, using 3-way merge.  This is done by giving
-'git-merge-one-file' command as one of the arguments to
+'git merge-one-file' command as one of the arguments to
 'git merge-index' command:
 
 ------------
@@ -1270,7 +1270,7 @@ ERROR: Merge conflict in hello
 fatal: merge program failed
 ------------
 
-'git-merge-one-file' script is called with parameters to
+'git merge-one-file' script is called with parameters to
 describe those three versions, and is responsible to leave the
 merge results in the working tree.
 It is a fairly straightforward shell script, and
@@ -1487,10 +1487,10 @@ If other people are pulling from your repository over dumb
 transport protocols (HTTP), you need to keep this repository
 'dumb transport friendly'.  After `git init`,
 `$GIT_DIR/hooks/post-update.sample` copied from the standard templates
-would contain a call to 'git-update-server-info'
+would contain a call to 'git update-server-info'
 but you need to manually enable the hook with
 `mv post-update.sample post-update`.  This makes sure
-'git-update-server-info' keeps the necessary files up-to-date.
+'git update-server-info' keeps the necessary files up-to-date.
 
 3. Push into the public repository from your primary
    repository.
diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt
index 5244925..dcdea54 100644
--- a/Documentation/gitdiffcore.txt
+++ b/Documentation/gitdiffcore.txt
@@ -23,7 +23,7 @@ that is easier to understand than the conventional kind.
 The chain of operation
 ----------------------
 
-The 'git-diff-{asterisk}' family works by first comparing two sets of
+The 'git diff-{asterisk}' family works by first comparing two sets of
 files:
 
  - 'git diff-index' compares contents of a "tree" object and the
@@ -74,12 +74,12 @@ into another list.  There are currently 5 such transformations:
 - diffcore-pickaxe
 - diffcore-order
 
-These are applied in sequence.  The set of filepairs 'git-diff-{asterisk}'
+These are applied in sequence.  The set of filepairs 'git diff-{asterisk}'
 commands find are used as the input to diffcore-break, and
 the output from diffcore-break is used as the input to the
 next transformation.  The final result is then passed to the
 output routine and generates either diff-raw format (see Output
-format sections of the manual for 'git-diff-{asterisk}' commands) or
+format sections of the manual for 'git diff-{asterisk}' commands) or
 diff-patch format.
 
 
@@ -87,7 +87,7 @@ diffcore-break: For Splitting Up "Complete Rewrites"
 ----------------------------------------------------
 
 The second transformation in the chain is diffcore-break, and is
-controlled by the -B option to the 'git-diff-{asterisk}' commands.  This is
+controlled by the -B option to the 'git diff-{asterisk}' commands.  This is
 used to detect a filepair that represents "complete rewrite" and
 break such filepair into two filepairs that represent delete and
 create.  E.g.  If the input contained this filepair:
@@ -123,7 +123,7 @@ diffcore-rename: For Detection Renames and Copies
 
 This transformation is used to detect renames and copies, and is
 controlled by the -M option (to detect renames) and the -C option
-(to detect copies as well) to the 'git-diff-{asterisk}' commands.  If the
+(to detect copies as well) to the 'git diff-{asterisk}' commands.  If the
 input contained these filepairs:
 
 ------------------------------------------------
@@ -168,11 +168,11 @@ number after the "-M" or "-C" option (e.g. "-M8" to tell it to use
 8/10 = 80%).
 
 Note.  When the "-C" option is used with `\--find-copies-harder`
-option, 'git-diff-{asterisk}' commands feed unmodified filepairs to
+option, 'git diff-{asterisk}' commands feed unmodified filepairs to
 diffcore mechanism as well as modified ones.  This lets the copy
 detector consider unmodified files as copy source candidates at
 the expense of making it slower.  Without `\--find-copies-harder`,
-'git-diff-{asterisk}' commands can detect copies only if the file that was
+'git diff-{asterisk}' commands can detect copies only if the file that was
 copied happened to have been modified in the same changeset.
 
 
@@ -223,7 +223,7 @@ diffcore-pickaxe: For Detecting Addition/Deletion of Specified String
 
 This transformation is used to find filepairs that represent
 changes that touch a specified string, and is controlled by the
--S option and the `\--pickaxe-all` option to the 'git-diff-{asterisk}'
+-S option and the `\--pickaxe-all` option to the 'git diff-{asterisk}'
 commands.
 
 When diffcore-pickaxe is in use, it checks if there are
@@ -246,7 +246,7 @@ diffcore-order: For Sorting the Output Based on Filenames
 
 This is used to reorder the filepairs according to the user's
 (or project's) taste, and is controlled by the -O option to the
-'git-diff-{asterisk}' commands.
+'git diff-{asterisk}' commands.
 
 This takes a text file each of whose lines is a shell glob
 pattern.  Filepairs that match a glob pattern on an earlier line
diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index 45559fa..87e2c03 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -202,7 +202,7 @@ updated. If the hook exits with zero, updating of individual refs can
 still be prevented by the <<update,'update'>> hook.
 
 Both standard output and standard error output are forwarded to
-'git-send-pack' on the other end, so you can simply `echo` messages
+'git send-pack' on the other end, so you can simply `echo` messages
 for the user.
 
 [[update]]
@@ -301,7 +301,7 @@ updated values of the refs. You might consider it instead if you need
 them.
 
 When enabled, the default 'post-update' hook runs
-'git-update-server-info' to keep the information used by dumb
+'git update-server-info' to keep the information used by dumb
 transports (e.g., HTTP) up-to-date.  If you are publishing
 a git repository that is accessible via HTTP, you should
 probably enable this hook.
@@ -313,8 +313,8 @@ for the user.
 pre-auto-gc
 ~~~~~~~~~~~
 
-This hook is invoked by 'git-gc --auto'. It takes no parameter, and
-exiting with non-zero status from this script causes the 'git-gc --auto'
+This hook is invoked by 'git gc --auto'. It takes no parameter, and
+exiting with non-zero status from this script causes the 'git gc --auto'
 to abort.
 
 GIT
diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt
index 5c4700c..3cd32d6 100644
--- a/Documentation/gitrepository-layout.txt
+++ b/Documentation/gitrepository-layout.txt
@@ -151,7 +151,7 @@ info/refs::
 	This file helps dumb transports discover what refs are
 	available in this repository.  If the repository is
 	published for dumb transports, this file should be
-	regenerated by 'git-update-server-info' every time a tag
+	regenerated by 'git update-server-info' every time a tag
 	or branch is created or modified.  This is normally done
 	from the `hooks/update` hook, which is run by the
 	'git-receive-pack' command when you 'git push' into the
-- 
1.6.6.218.g502b0

[PATCH 2/2] More missed `code snippets`

[Thomas Rast]

Squashed into the corresponding commit of the original series.
---

Additionally, I reverted

   --- i/Documentation/git-bisect.txt
   +++ w/Documentation/git-bisect.txt
   @@ -26,7 +26,7 @@ on the subcommand:
     git bisect log
     git bisect run <cmd>...

   -This command uses `git rev-list --bisect` to help drive the
   +This command uses 'git rev-list --bisect' to help drive the
    binary search process to find which change introduced a bug, given an
    old "good" commit object name and a later "bad" commit object name.

per the review.

 Documentation/config.txt |    2 +-
 Documentation/git-gc.txt |    2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git i/Documentation/config.txt w/Documentation/config.txt
index 6bfd9e1..3e96a27 100644
--- i/Documentation/config.txt
+++ w/Documentation/config.txt
@@ -747,7 +747,7 @@ diff.mnemonicprefix::
 	 compares a (c)ommit and the (w)ork tree;
 `git diff --cached`;;
 	compares a (c)ommit and the (i)ndex;
-`git-diff HEAD:file1 file2`;;
+`git diff HEAD:file1 file2`;;
 	compares an (o)bject and a (w)ork tree entity;
 `git diff --no-index a b`;;
 	compares two non-git things (1) and (2).
diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt
index 771807f..189573a 100644
--- a/Documentation/git-gc.txt
+++ b/Documentation/git-gc.txt
@@ -50,7 +50,7 @@ Housekeeping is required if there are too many loose objects or
 too many packs in the repository. If the number of loose objects
 exceeds the value of the `gc.auto` configuration variable, then
 all loose objects are combined into a single pack using
-'git repack -d -l'.  Setting the value of `gc.auto` to 0
+`git repack -d -l`.  Setting the value of `gc.auto` to 0
 disables automatic packing of loose objects.
 +
 If the number of packs exceeds the value of `gc.autopacklimit`,
-- 
1.6.6.218.g502b0

[PATCH] Documentation: show-files is now called git-ls-files

[Thomas Rast]

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

However, the tool is now called git-ls-files.

Signed-off-by: Thomas Rast <trast@student.ethz.ch>
---
 Documentation/git-ls-files.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 7faba23..a84cc37 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -140,7 +140,7 @@ OPTIONS
 
 Output
 ------
-show files just outputs the filename unless '--stage' is specified in
+'git ls-files' just outputs the filenames unless '--stage' is specified in
 which case it outputs:
 
         [<tag> ]<mode> <object> <stage> <file>
-- 
1.6.6.218.g502b0

Re: [PATCH v2 2/4] Documentation: warn prominently against merging with dirty trees

[Thomas Rast]

Junio C Hamano wrote:
> >> while possible, it leaves you in a state that is hard to
> >> +back out of in the case of a conflict.
> >> +
> >
> > Oh, that is a problem.  Maybe 'git merge' should refuse to merge
> > unless told otherwise, if there is a dirty index and there might be
> > conflicts.

Actually I'm worried about a dirty *worktree*.  Do you think that
should be clarified?

> "git reset --merge" will keep your local changes after such a merge, and
> "mergy" operations (not just "merge" but also "revert", "am -3", etc)
> won't get you into a situation where you cannot, by refusing to do
> anything when e.g. your index is dirty.  Especially when Christian's
> "reset --merge" update becomes solid, "... is hard to back out of" will
> become a false statement.

Does that apply to dirty worktrees, too?  I admit I didn't follow that
topic at all.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

Re: [PATCH v2 4/4] Documentation: spell 'git cmd' without dash throughout

[Thomas Rast]

Jonathan Nieder wrote:
> >  110 files changed, 584 insertions(+), 584 deletions(-)
> 
> But yikes!  Did you do this by hand or by some automated process?

The (now-refined) bottom line is

  perl -i -pe "s{'git-((?"'!'"cvsserver|upload-pack|receive-pack|shell|upload-archive)[a-z-]+)}{'git \$1}g" Documentation/*.txt
  git checkout -- Documentation/RelNotes*
  git add -p

I really stepped through all of them with 'git add -p', but my eyes
probably got tired rather quickly.

> A 'git-apply' snuck in. ;-)

Indeed, and (as you can see in the update I sent a few minutes ago) I
missed a lot more, because I originally had a regex that only scanned
for 'git-cmd' and 'git-split-cmd', missing the 'git-three-word-cmd'
and 'git-cmd --with-option' forms.  Thanks for pointing that out.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

Re: [PATCH v2 1/4] Documentation/git-merge: reword references to "remote" and "pull"

[Thomas Rast]

Jonathan Nieder wrote:
> Thomas Rast wrote:
> >   * Look at the diffs.  'git diff' will show a three-way diff,
> > -   highlighting changes from both the HEAD and remote versions.
> > +   highlighting changes from both the HEAD and their versions.
> >  
> >   * Look at the diffs on their own. 'git log --merge -p <path>'
> 
> This is a bit awkward, since 'they' is playing two roles.  Also,
> the context does not make it obvious what 'our' and 'their'
> versions are.
> 
> Maybe:
> 
> |   * Look at the diffs.  'git diff' will show a three-way diff,
> |     highlighting changes from both the HEAD and MERGE_HEAD
> |     versions.

I like this idea, as it nicely assigns terminology to the "their"
side.  We need to explain MERGE_HEAD (it's not in the manpage yet),
but that should fit in somewhere.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

Re: [PATCH v2 2/4] Documentation: warn prominently against merging with dirty trees

[Jonathan Nieder]

Junio C Hamano wrote:
> Jonathan Nieder <jrnieder@gmail.com> writes:

>> Oh, that is a problem.  Maybe 'git merge' should refuse to merge
>> unless told otherwise, if there is a dirty index and there might be
>> conflicts.
>
> "git reset --merge" will keep your local changes after such a merge, and
> "mergy" operations (not just "merge" but also "revert", "am -3", etc)
> won't get you into a situation where you cannot, by refusing to do
> anything when e.g. your index is dirty.  Especially when Christian's
> "reset --merge" update becomes solid, "... is hard to back out of" will
> become a false statement.

Here is a scenario I worry about:

Suppose I have a change to main.c staged, to add a feature that others
have discussed as well.  After a short distraction, I return and run
‘git pull’ to see what upstream has been working on.  As luck would
have it, the remote version of main.c is exactly the same as my
modified version, so the merge happily proceeds.  Some other files
merge cleanly.  Eventually there is some conflict.

Now I regret the pull.  Will ‘reset --merge’ restore the index and
work tree to its original state?

If the change to main.c was _not_ staged, then the merge would have
failed early, so that is not something to worry about.

> Of course, the user needs to understand what he or she is doing (see
> http://thread.gmane.org/gmane.comp.version-control.git/136166/focus=136171
> for example).

Agreed.  And probably the user who understands what is going on will
not make the mistake I described above.  Otherwise, they could succumb
to a related problem:

Suppose all is as above, except that git detects no conflict.  Suppose
further that some upstream commit was bogus.

Now I regret the pull.  How can I restore the index and work tree to
its original state?

If I reset --hard (or --merge) to the previous HEAD commit, the
modification to main.c is forgotten.  In practice, I would do
'git reset --hard HEAD^ && git checkout HEAD@{1} -- main.c'.

Re: [PATCH v2 2/4] Documentation: warn prominently against merging with dirty trees

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Here is a scenario I worry about:
>
> Suppose I have a change to main.c staged, to add a feature that others
> have discussed as well.  After a short distraction, I return and run
> ‘git pull’ to see what upstream has been working on.

If your index is dirty, any "mergy" operation will refuse to work *before*
touching anything, so you won't use "git reset --merge" to begin with.

You are allowed to have local modifications only in your work tree.
Furthermore, even git experts limit them to something they feel they can
afford to lose and recreate easily if necessary.  See for example:

  http://thread.gmane.org/gmane.comp.version-control.git/15148/focus=15476

That is why I said:

  Of course, the user needs to understand what he or she is doing (see
  http://thread.gmane.org/gmane.comp.version-control.git/136166/focus=136171
  for example).  And that is one reason we (at least I) try to teach new
  people to start working from a clean tree, until they get comfortable
  working with mergy operations.

and that is why the archived article referenced above refers to

  http://gitster.livejournal.com/29060.html

You need to be able to tell the two ways in which a "mergy" operation can
"fail" apart [*1*].

 - One that stops before touching anything (either your index was dirty
   and nothing happened, or your index was clean but you had local
   modifications in your work tree).  You do not run "git reset --merge",
   for this one; and

 - Another that goes ahead and results in conflicts.  When you got these
   conflicts, you can "reset --merge" them away.

[Footnote]

*1* Strictly speaking, the latter is not even a "failure"; it allowed you
to make progress, merging all the auto-mergeable parts without your help,
and only asking you to handle the remainder.

Re: [PATCH v2 2/4] Documentation: warn prominently against merging with dirty trees

[Jonathan Nieder]

Junio C Hamano wrote:
> Jonathan Nieder <jrnieder@gmail.com> writes:

>> Here is a scenario I worry about:
>>
>> Suppose I have a change to main.c staged, to add a feature that others
>> have discussed as well.  After a short distraction, I return and run
>> ‘git pull’ to see what upstream has been working on.
>
> If your index is dirty, any "mergy" operation will refuse to work *before*
> touching anything, so you won't use "git reset --merge" to begin with.

Yes, that is true.  And I was not worried about that.

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. In
| other words, git diff --cached HEAD must report no changes. (One exception
| is when the changed index entries are already in the same state that would
| result from the merge anyway.)

The potentially problematic scenario for "git reset --merge" is this
last one, where a changed index entry is already in the same state
that would result from the merge.  Would a "git reset --merge" reset
the changed contents away?

> You are allowed to have local modifications only in your work tree.
> Furthermore, even git experts limit them to something they feel they can
> afford to lose and recreate easily if necessary.

Sadly, even a small change disappearing can be unnerving for an expert
and dangerous for a novice.

> You need to be able to tell the two ways in which a "mergy" operation can
> "fail" apart [*1*].

Thanks for bringing this up.  The manual does not emphasize that
point at all, but it should.

Jonathan

[PATCH 0/6] Re: Documentation: warn prominently against merging with dirty trees

[Jonathan Nieder]

Jonathan Nieder wrote:
> Junio C Hamano wrote:

>> You need to be able to tell the two ways in which a "mergy" operation can
>> "fail" apart [*1*].
>
> Thanks for bringing this up.  The manual does not emphasize that
> point at all, but it should.

Maybe something like this (patch 4) could help.  This should pass
through Thomas’s tree to avoid conflicts with his other changes; but
of course, I would be glad to hear any thoughts you have before then.

Jonathan Nieder (6):
  Documentation: clarify one-line description for merge
  Documentation: merge: add an overview
  Documentation: merge: move configuration section to the end
  Documentation: emphasize when git merge terminates early
  Documentation: merge: add a section about fast-forward
  Documentation: merge: tweak HOW MERGE WORKS section

 Documentation/git-merge.txt |  149 ++++++++++++++++++++++++++----------------
 1 files changed, 92 insertions(+), 57 deletions(-)

[PATCH/RFC 1/6] Documentation: clarify one-line description for merge

[Jonathan Nieder]

The 'git merge' command is generally not used to tie completely
independent projects together (though it can be used to do that)
but to reconcile branches of development that may have diverged.
Try to make this clearer in its one-line description.

Cc: Petr Baudis <pasky@suse.cz>
Cc: Junio C Hamano <gitster@pobox.com>
Cc: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
I am not sure this is an improvement at all.  Mostly I wanted to
convey the idea of code forks being reconciled, but the resulting
phrase is not nearly as nice.

 Documentation/git-merge.txt |    3 +--
 1 files changed, 1 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index e886c2e..394ad0a 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -3,8 +3,7 @@ git-merge(1)
 
 NAME
 ----
-git-merge - Join two or more development histories together
-
+git-merge - Re-join diverging branches of development
 
 SYNOPSIS
 --------
-- 
1.6.6

[PATCH 2/6] Documentation: merge: add an overview

[Jonathan Nieder]

The reader unfamiliar with the concepts of branching and merging
would have been completely lost.  Try to help him with a diagram.

The diagram comes from the 'git rebase' manual page.

Cc: Petr Baudis <pasky@suse.cz>
Cc: Junio C Hamano <gitster@pobox.com>
Cc: Thomas Rast <trast@student.ethz.ch>,
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
Does this tell enough of the story?

 Documentation/git-merge.txt |   27 +++++++++++++++++++++++++--
 1 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 394ad0a..fe190e2 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -14,8 +14,31 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-This is the top-level interface to the merge machinery
-which drives multiple merge strategy scripts.
+Incorporates changes leading up to the named commits into the
+current branch.  This command is used by 'git pull' to incorporate
+remote changes from another repository and may be used by hand to
+merge changes from one branch into another.
+
+Assume the following history exists and the current branch is
+"`master`":
+
+------------
+          A---B---C topic
+         /
+    D---E---F---G master
+------------
+
+Then "`git merge topic`" will apply the changes from `A`, `B`,
+and `C` to the work tree, and if they do not conflict with any
+changes from `master`, will store the result in a new commit along
+with the names of the two parent commits and a log message from the
+user describing the changes.
+
+------------
+          A---B---C topic
+         /         \
+    D---E---F---G---H master
+------------
 
 The second syntax (<msg> `HEAD` <remote>) is supported for
 historical reasons.  Do not use it from the command line or in
-- 
1.6.6

[PATCH 4/6] Documentation: emphasize when git merge terminates early

[Jonathan Nieder]

A merge-based operation in git can fail in two ways:

 - One that stops before touching anything (either your index was
   dirty and nothing happened, or your index was clean but you
   had local modifications in your work tree).

 - Another that goes ahead and results in conflicts.

The 'git merge' manual explains half of the first case as follows:

| 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.

The placement of this sentence makes it easy to skip over, and
its formulation is perhaps too formal to be memorable.

So give this point its own section and expand upon it.  Most of
the added text is taken from <http://gitster.livejournal.com/25801.html>.

Cc: Petr Baudis <pasky@suse.cz>,
Cc: Junio C Hamano <gitster@pobox.com>
Cc: Thomas Rast <trast@student.ethz.ch>
Not-signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
This is not signed off because most of the text is from Junio’s
blog.  I hope that is okay.

 Documentation/git-merge.txt |   34 ++++++++++++++++++++++++----------
 1 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index e29bb97..8950aa4 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -60,6 +60,28 @@ include::merge-options.txt[]
 	least one <remote>.  Specifying more than one <remote>
 	obviously means you are trying an Octopus.
 
+PRE-MERGE CHECKS
+----------------
+
+In some other version control systems, you merge/update and then
+commit, with the risk of clobbering your changes with humongous
+conflicts. You shouldn't be pulling or merging if you haven't got
+your own work into good shape and committed it locally (see also
+linkgit:git-stash[1]).
+
+But novices can make this mistake, and 'git pull' and 'git merge'
+will stop without doing anything when local uncommitted changes
+overlap with files that 'git pull'/'git merge' may need to update.
+
+Also, to avoid unrelated changes in the recorded commit, 'git
+pull' and 'git merge' abort if there are any changes registered
+in the index relative to the contents of the `HEAD` commit.
+(One exception is when the changed index entries are already in
+the same state that would result from the merge anyway.)
+
+If all named commits are already ancestors of `HEAD`, 'git merge'
+will exit early with the message "Already up-to-date."
+
 include::merge-strategies.txt[]
 
 
@@ -70,17 +92,9 @@ HOW MERGE WORKS
 ---------------
 
 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.  In other words, `git diff --cached HEAD` must
-report no changes.  (One exception is when the changed index
-entries are already in the same state that would result from
-the merge anyway.)
-
-Three kinds of merge can happen:
+commits (usually, branch head or tag).
 
-* The merged commit is already contained in `HEAD`. This is the
-  simplest case, called "Already up-to-date."
+Two kinds of merge can happen:
 
 * `HEAD` is already contained in the merged commit. This is the
   most common case especially when invoked from 'git pull':
-- 
1.6.6

[PATCH 5/6] Documentation: merge: add a section about fast-forward

[Jonathan Nieder]

Novices sometimes find the behavior of 'git merge' in the
fast-forward case surprising.  Add a section to the manual to
describe it more thoroughly.

Cc: Petr Baudis <pasky@suse.cz>,
Cc: Junio C Hamano <gitster@pobox.com>
Cc: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-merge.txt |   31 ++++++++++++++++++-------------
 1 files changed, 18 insertions(+), 13 deletions(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 8950aa4..ec9c6d3 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -82,6 +82,20 @@ the same state that would result from the merge anyway.)
 If all named commits are already ancestors of `HEAD`, 'git merge'
 will exit early with the message "Already up-to-date."
 
+FAST-FORWARD MERGE
+------------------
+
+Often the current branch head is an ancestor of the named commit.
+This is the most common case especially when invoked from 'git
+pull': you are tracking an upstream repository, you have committed
+no local changes, and now you want to update to a newer upstream
+revision.  In this case, a new commit is not needed to store the
+combined history; instead, the `HEAD` (along with the index) is
+updated to point at the named commit, without creating an extra
+merge commit.
+
+This behavior can be suppressed with the `--no-ff` option.
+
 include::merge-strategies.txt[]
 
 
@@ -94,19 +108,10 @@ HOW MERGE WORKS
 A merge is always between the current `HEAD` and one or more
 commits (usually, branch head or tag).
 
-Two kinds of merge can happen:
-
-* `HEAD` is already contained in the merged commit. This is the
-  most common case especially when invoked from 'git pull':
-  you are tracking an upstream repository, have committed no local
-  changes and now you want to update to a newer upstream revision.
-  Your `HEAD` (and the index) is updated to point at the merged
-  commit, without creating an extra merge commit.  This is
-  called "Fast-forward".
-
-* Both the merged commit and `HEAD` are independent and must be
-  tied together by a merge commit that has both of them as its parents.
-  The rest of this section describes this "True merge" case.
+Except in a fast-forward merge (see above), the branches to be
+merged must be tied together by a merge commit that has both of them
+as its parents.
+The rest of this section describes this "True merge" case.
 
 The chosen merge strategy merges the two commits into a single
 new source tree.
-- 
1.6.6

[PATCH 6/6] Documentation: tweak How Merge Works

[Jonathan Nieder]

Change heading to TRUE MERGE.  The whole manual page is about how
merges work.

Start to explain what it means to merge two commits into a single
tree.

Do not assume the commits named on the 'git merge' command line
come from another repository.  For simplicity, still assume they
are branch heads for now, though.

Do not give start any list items with `code`; a toolchain bug
makes the resulting nroff look wrong.

Recommend reset --merged for safely cancelling a failed merge.

Cc: Petr Baudis <pasky@suse.cz>
Cc: Junio C Hamano <gitster@pobox.com>
Cc: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-merge.txt |   56 +++++++++++++++++++-----------------------
 1 files changed, 25 insertions(+), 31 deletions(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index ec9c6d3..7ae0f65 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -96,62 +96,56 @@ merge commit.
 
 This behavior can be suppressed with the `--no-ff` option.
 
-include::merge-strategies.txt[]
-
-
-If you tried a merge which resulted in complex conflicts and
-want to start over, you can recover with 'git-reset'.
-
-HOW MERGE WORKS
----------------
-
-A merge is always between the current `HEAD` and one or more
-commits (usually, branch head or tag).
+TRUE MERGE
+----------
 
 Except in a fast-forward merge (see above), the branches to be
 merged must be tied together by a merge commit that has both of them
 as its parents.
 The rest of this section describes this "True merge" case.
 
-The chosen merge strategy merges the two commits into a single
-new source tree.
 When things merge cleanly, this is what happens:
 
-1. The results are updated both in the index file and in your
-   working tree;
-2. Index file is written out as a tree;
+1. A version reconciling the changes from all branches to be
+   merged is written to the index file and your working tree;
+2. The index file is written out as a tree;
 3. The tree gets committed; and
 4. The `HEAD` pointer gets advanced.
 
 Because of 2., we require that the original state of the index
 file matches exactly the current `HEAD` commit; otherwise we
-will write out your local changes already registered in your
+would write out your local changes already registered in your
 index file along with the merge result, which is not good.
 Because 1. involves only those paths differing between your
-branch and the remote branch you are pulling from during the
-merge (which is typically a fraction of the whole tree), you can
-have local modifications in your working tree as long as they do
-not overlap with what the merge updates.
-
-When there are conflicts, the following happens:
+branch and the other branches (which is typically a fraction of
+the whole tree), you can have local modifications in your
+working tree as long as they do not overlap with what the merge
+updates.
 
-1. `HEAD` stays the same.
+When it is not obvious how to reconcile the changes, the following
+happens:
 
-2. Cleanly merged paths are updated both in the index file and
+1. The `HEAD` pointer stays the same.
+2. The `MERGE_HEAD` ref is set to point to the other branch head.
+3. Paths that merged cleanly are updated both in the index file and
    in your working tree.
-
-3. For conflicting paths, the index file records up to three
+4. For conflicting paths, the index file records up to three
    versions; stage1 stores the version from the common ancestor,
-   stage2 from `HEAD`, and stage3 from the remote branch (you
+   stage2 from `HEAD`, and stage3 from `MERGE_HEAD` (you
    can inspect the stages with `git ls-files -u`).  The working
    tree files contain the result of the "merge" program; i.e. 3-way
-   merge results with familiar conflict markers `<<< === >>>`.
-
-4. No other changes are done.  In particular, the local
+   merge results with familiar conflict markers `<<<` `===` `>>>`.
+5. No other changes are done.  In particular, the local
    modifications you had before you started merge will stay the
    same and the index entries for them stay as they were,
    i.e. matching `HEAD`.
 
+If you tried a merge which resulted in complex conflicts and
+want to start over, you can recover with `git reset --merged`.
+
+include::merge-strategies.txt[]
+
+
 HOW CONFLICTS ARE PRESENTED
 ---------------------------
 
-- 
1.6.6

Re: [PATCH 2/6] Documentation: merge: add an overview

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> The reader unfamiliar with the concepts of branching and merging
> would have been completely lost.  Try to help him with a diagram.

Good idea.

>  DESCRIPTION
>  -----------
> -This is the top-level interface to the merge machinery
> -which drives multiple merge strategy scripts.
> +Incorporates changes leading up to the named commits into the
> +current branch.

Having "since the histories diverged" somewhere in this first sentence
would clarify the concepts better, I think.

> +Assume the following history exists and the current branch is
> +"`master`":
> +
> +------------
> +          A---B---C topic
> +         /
> +    D---E---F---G master
> +------------
> +
> +Then "`git merge topic`" will apply the changes from `A`, `B`,
> +and `C` to the work tree, and if they do not conflict with any
> +changes from `master`, will store the result in a new commit along
> +with the names of the two parent commits and a log message from the
> +user describing the changes.

 - Don't spell A, B and C out; technically we don't do that, and
   conceptually "changes since E until C" is exactly the same.

 - Don't talk about "what it does" first, but talk about "what it is used
   for" iow "why do you want to use it".

 - "What it is used for" doesn't have to talk about "if it does not
   conflict" yet; it is merely a lower-level detail that the main part of
   the document can teach the users to help the tool achieve its goal
   (i.e. "what it is used for") when it cannot do so automatically.

	`git merge topic` is used to replay the change the topic has made
        since it diverged from master's history (i.e. E) until its current
        commit (i.e. C) on top of master, and store the result in a new
        commit along with....

> +------------
> +          A---B---C topic
> +         /         \
> +    D---E---F---G---H master
> +------------
>  
>  The second syntax (<msg> `HEAD` <remote>) is supported for
>  historical reasons.  Do not use it from the command line or in
> -- 
> 1.6.6

Re: [PATCH 6/6] Documentation: tweak How Merge Works

[Thomas Rast]

The below and earlier comments aside, I really like this series.  It
seems to make the manpage much more accessible.

Jonathan Nieder wrote:
> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> index ec9c6d3..7ae0f65 100644
> --- a/Documentation/git-merge.txt
> +++ b/Documentation/git-merge.txt
> @@ -96,62 +96,56 @@ merge commit.
>  
>  This behavior can be suppressed with the `--no-ff` option.
>  
> -include::merge-strategies.txt[]
> -
> -

I'm not sure whether you deliberately did this, or deliberately
deferred it to this patch, but this "sneak moves" the merge-strategies
section beyond "TRUE MERGE" (was "HOW MERGE WORKS").

So the section layout changes as follows when comparing current master
with your series:

 NAME
 SYNOPSIS
 DESCRIPTION
 OPTIONS
+PRE-MERGE CHECKS
+FAST-FORWARD MERGE
+TRUE MERGE
 MERGE STRATEGIES
-CONFIGURATION
-HOW MERGE WORKS
 HOW CONFLICTS ARE PRESENTED
 HOW TO RESOLVE CONFLICTS
 EXAMPLES
+CONFIGURATION
 SEE ALSO
 AUTHOR
 DOCUMENTATION
 GIT
 NOTES

While I agree with the general intent of deferring the strategies
further back, wouldn't it be better go all the way and instead put
them before (or even after, but one of them uses -s ours) "EXAMPLES"?
The average user will care more about conflicts than about strategies
other than 'recursive'.

> +1. A version reconciling the changes from all branches to be
> +   merged is written to the index file and your working tree;
> +2. The index file is written out as a tree;
>  3. The tree gets committed; and
>  4. The `HEAD` pointer gets advanced.

Could we do away with the detail here?  The user most likely does not
care about the exact order because he cannot "see" it happening
anyway.  So how about

  A merged version reconciling the changes from all branches to be
  merged is committed, and your HEAD, index, and working tree are
  updated to it.  (It is possible to have modifications in the working
  tree as long as they do not overlap; the update will preserve them.)

and then snip everything up to

> +When it is not obvious how to reconcile the changes, the following
> +happens:

because that is far more important to the user: he is left in the
middle of the described state.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

Re: [PATCH 4/6] Documentation: emphasize when git merge terminates early

[Thomas Rast]

Jonathan Nieder wrote:
> +In some other version control systems, you merge/update and then
> +commit, with the risk of clobbering your changes with humongous
> +conflicts. You shouldn't be pulling or merging if you haven't got
> +your own work into good shape and committed it locally (see also
> +linkgit:git-stash[1]).

Isn't it wrong to talk about other VCS, especially when writing down
what Git does *not*?  The user wants to know what git *does*,
otherwise he wouldn't be looking in the manual.

> +If all named commits are already ancestors of `HEAD`, 'git merge'
> +will exit early with the message "Already up-to-date."

<aside>
I suspect this is little-known but the equivalent message for an
octopus is actually: "Already up-to-date. Yeeah!"
</aside>

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

Re: [PATCH v2 2/4] Documentation: warn prominently against merging with dirty trees

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> | 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. In
> | other words, git diff --cached HEAD must report no changes. (One exception
> | is when the changed index entries are already in the same state that would
> | result from the merge anyway.)
>
> The potentially problematic scenario for "git reset --merge" is this
> last one, where a changed index entry is already in the same state
> that would result from the merge.  Would a "git reset --merge" reset
> the changed contents away?

It will discard the change, the one you independently picked up, but the
change agreed with what was done by the the trash history that you are
cancelling merge with.  You wouldn't miss losing the same change as in
that trash history.

Re: [PATCH 0/6] Re: Documentation: warn prominently against merging with dirty trees

[Petr Baudis]

On Mon, Jan 11, 2010 at 02:21:23AM -0600, Jonathan Nieder wrote:
> Jonathan Nieder (6):
>   Documentation: clarify one-line description for merge

I don't think this is an improvement and prefer the original phrasing.

>   Documentation: merge: move configuration section to the end

Ack.

I will reply to the other patches in separate mails.

				Petr "Pasky" Baudis

Re: [PATCH v2 0/4] Documentation style fixes

[Junio C Hamano]

I think we have given people enough time to comment, so I am going to
merge 0b444cd (Documentation: spell 'git cmd' without dash throughout,
2010-01-10) which was taken from the tip of your for-next branch and that
has been in 'pu' for the last week.

Re: [PATCH v2 0/4] Documentation style fixes

[Thomas Rast]

Junio C Hamano wrote:
> I think we have given people enough time to comment, so I am going to
> merge 0b444cd (Documentation: spell 'git cmd' without dash throughout,
> 2010-01-10) which was taken from the tip of your for-next branch and that
> has been in 'pu' for the last week.

Ok, thanks.

Jonathan, do you plan on rerolling your 6-patch series with Pasky's
and my comments?  Otherwise I might give it a stab, since I like the
series and it would be a shame to just forget about it.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

Re: [PATCH v2 0/4] Documentation style fixes

[Jonathan Nieder]

Thomas Rast wrote:

> Jonathan, do you plan on rerolling your 6-patch series with Pasky's
> and my comments?

Yes, I was planning to get to it today; sorry for the lack of noise.

Jonathan

[PATCH] Documentation: merge: use MERGE_HEAD to refer to the remote branch

[Jonathan 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 <jrnieder@gmail.com>
---
Thomas Rast wrote:
> Jonathan Nieder wrote:

>> Maybe:
>> 
>> |   * Look at the diffs.  'git diff' will show a three-way diff,
>> |     highlighting changes from both the HEAD and MERGE_HEAD
>> |     versions.
>
> I like this idea, as it nicely assigns terminology to the "their"
> side.  We need to explain MERGE_HEAD (it's not in the manpage yet),
> but that should fit in somewhere.

Here is a try.  This applies on top of the series to clarify 'git
merge' documentation [1] I sent earlier today, which conveniently
enough explains MERGE_HEAD a few sections earlier.

Thanks for the encouragement,
Jonathan

[1] http://thread.gmane.org/gmane.comp.version-control.git/137818

 Documentation/git-merge.txt |   14 ++++++++------
 1 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 7aa3f3f..4b1b2f5 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -215,15 +215,17 @@ You can work through the conflict with a number of tools:
    mergetool which will work you through the merge.
 
  * Look at the diffs.  `git diff` will show a three-way diff,
-   highlighting changes from both the HEAD and their versions.
+   highlighting changes from both the `HEAD` and `MERGE_HEAD`
+   versions.
 
- * Look at the diffs on their own. `git log --merge -p <path>`
-   will show diffs first for the HEAD version and then
-   their version.
+ * Look at the diffs from each branch. `git log --merge -p <path>`
+   will show diffs first for the `HEAD` version and then the
+   `MERGE_HEAD` version.
 
  * Look at the originals.  `git show :1:filename` shows the
-   common ancestor, `git show :2:filename` shows the HEAD
-   version and `git show :3:filename` shows their version.
+   common ancestor, `git show :2:filename` shows the `HEAD`
+   version, and `git show :3:filename` shows the `MERGE_HEAD`
+   version.
 
 
 EXAMPLES
-- 
1.6.6