[PATCH 0/13] Modernize user-manual

Hi,

command output has changed for some commands in the last years,
so reflect this also in the user-manual. While doing so, fix some minor 
spelling, formatting and wording issues.

Further, some references and recommendations which nowadays might 
only confuse and not help new Git users where removed. Also some 
explanations where rephrased to IMHO make them easier to understand
for new users.

The last patch removes a lengthy paragraph which states that "git prune" 
(and "git fsck") should only be used in a quiescent repository.  The 
man-page for "git prune" tells nothing about this. So either the 
removal should be OK or we have to duplicate the warning paragraph 
in the man-page of "git prune"?

[PATCH 01/13] Call it "Git User Manual" and remove reference to very old Git version
[PATCH 02/13] Use current "detached HEAD" message
[PATCH 03/13] Use current output for "git repack"
[PATCH 04/13] Use "git merge" instead of "git pull ."
[PATCH 05/13] Fix some typos
[PATCH 06/13] Simplify "How to make a commit"
[PATCH 07/13] Improve description in "How to merge"
[PATCH 08/13] Improve section "Manipulating branches"
[PATCH 09/13] Improve section "Merge multiple trees"
[PATCH 10/13] Remove unnecessary historical note from "Object storage format"
[PATCH 11/13] Remove obscure reference from "Examples"
[PATCH 12/13] Remove irrelevant reference from "Tying it all together"
[PATCH 13/13] "git prune" is safe now

Signed-off-by: Thomas Ackermann <redacted>


---
Thomas

Signed-off-by: Thomas Ackermann <redacted>
---
 Documentation/user-manual.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index fe723e4..103ec9a 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt

@@ -1,6 +1,5 @@
-Git User's Manual (for version 1.5.3 or newer)
-______________________________________________
-
+Git User Manual
+_______________
 
 Git is a fast distributed revision control system.
 

-- 
1.8.3.msysgit.0


---
Thomas

Signed-off-by: Thomas Ackermann <redacted>
---
 Documentation/user-manual.txt | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 103ec9a..cb30929 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt

@@ -312,10 +312,17 @@ referenced by a tag:
 
 ------------------------------------------------
 $ git checkout v2.6.17
-Note: moving to "v2.6.17" which isn't a local branch
-If you want to create a new branch from this checkout, you may do so
-(now or later) by using -b with the checkout command again. Example:
-  git checkout -b <new_branch_name>
+Note: checking out 'v2.6.17'.
+
+You are in 'detached HEAD' state. You can look around, make experimental
+changes and commit them, and you can discard any commits you make in this
+state without impacting any branches by performing another checkout.
+
+If you want to create a new branch to retain commits you create, you may
+do so (now or later) by using -b with the checkout command again. Example:
+
+  git checkout -b new_branch_name
+
 HEAD is now at 427abfa... Linux v2.6.17
 ------------------------------------------------
 

@@ -326,7 +333,7 @@ and git branch shows that you are no longer on a branch:
 $ cat .git/HEAD
 427abfa28afedffadfca9dd8b067eb6d36bac53f
 $ git branch
-* (no branch)
+* (detached from v2.6.17)
   master
 ------------------------------------------------
 

-- 
1.8.3.msysgit.0


---
Thomas

Signed-off-by: Thomas Ackermann <redacted>
---
 Documentation/user-manual.txt | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index cb30929..b450980 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt

@@ -3203,14 +3203,11 @@ To put the loose objects into a pack, just run git repack:
 
 ------------------------------------------------
 $ git repack
-Generating pack...
-Done counting 6020 objects.
-Deltifying 6020 objects.
- 100% (6020/6020) done
-Writing 6020 objects.
- 100% (6020/6020) done
-Total 6020, written 6020 (delta 4070), reused 0 (delta 0)
-Pack pack-3e54ad29d5b2e05838c75df582c65257b8d08e1c created.
+Counting objects: 6020, done.
+Delta compression using up to 4 threads.
+Compressing objects: 100% (6020/6020), done.
+Writing objects: 100% (6020/6020), done.
+Total 6020 (delta 4070), reused 0 (delta 0)
 ------------------------------------------------
 
 You can then run

-- 
1.8.3.msysgit.0


---
Thomas

"git pull ." works, but "git merge" is the recommended
way for new users to do things. (The old description 
also should have read "The former is actually *not* very
commonly used".)

Signed-off-by: Thomas Ackermann <redacted>
---
 Documentation/user-manual.txt | 15 ++-------------
 1 file changed, 2 insertions(+), 13 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index b450980..8a1a441 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt

@@ -1784,17 +1784,6 @@ repository that you pulled from.
 <<fast-forwards,fast-forward>>; instead, your branch will just be
 updated to point to the latest commit from the upstream branch.)
 
-The `git pull` command can also be given `.` as the "remote" repository,
-in which case it just merges in a branch from the current repository; so
-the commands
-
--------------------------------------------------
-$ git pull . branch
-$ git merge branch
--------------------------------------------------
-
-are roughly equivalent.  The former is actually very commonly used.
-
 [[submitting-patches]]
 Submitting patches to a project
 -------------------------------

@@ -2259,7 +2248,7 @@ When you are happy with the state of this change, you can pull it into the
 "test" branch in preparation to make it public:
 
 -------------------------------------------------
-$ git checkout test && git pull . speed-up-spinlocks
+$ git checkout test && git merge speed-up-spinlocks
 -------------------------------------------------
 
 It is unlikely that you would have any conflicts here ... but you might if you

@@ -2271,7 +2260,7 @@ see the value of keeping each patch (or patch series) in its own branch.  It
 means that the patches can be moved into the `release` tree in any order.
 
 -------------------------------------------------
-$ git checkout release && git pull . speed-up-spinlocks
+$ git checkout release && git merge speed-up-spinlocks
 -------------------------------------------------
 
 After a while, you will have a number of branches, and despite the

-- 
1.8.3.msysgit.0


---
Thomas

Signed-off-by: Thomas Ackermann <redacted>
---
 Documentation/user-manual.txt | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index ca78333..ccbddc7 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt

@@ -219,7 +219,7 @@ of development leading to that point.
 
 The best way to see how this works is using the linkgit:gitk[1]
 command; running gitk now on a Git repository and looking for merge
-commits will help understand how the Git organizes history.
+commits will help understand how Git organizes history.
 
 In the following, we say that commit X is "reachable" from commit Y
 if commit X is an ancestor of commit Y.  Equivalently, you could say

@@ -793,7 +793,7 @@ e05db0fd4f31dde7005f075a84f96b360d05984b
 -------------------------------------------------
 
 Or you could recall that the `...` operator selects all commits
-contained reachable from either one reference or the other but not
+reachable from either one reference or the other but not
 both; so
 
 -------------------------------------------------

@@ -820,7 +820,7 @@ You could just visually inspect the commits since e05db0fd:
 $ gitk e05db0fd..
 -------------------------------------------------
 
-Or you can use linkgit:git-name-rev[1], which will give the commit a
+or you can use linkgit:git-name-rev[1], which will give the commit a
 name based on any tag it finds pointing to one of the commit's
 descendants:
 

@@ -3525,7 +3525,7 @@ with Git 1.5.2 can look up the submodule commits in the repository and
 manually check them out; earlier versions won't recognize the submodules at
 all.
 
-To see how submodule support works, create (for example) four example
+To see how submodule support works, create four example
 repositories that can be used later as a submodule:
 
 -------------------------------------------------

@@ -3897,7 +3897,7 @@ fact that such a commit brings together ("merges") two or more
 previous states represented by other commits.
 
 In other words, while a "tree" represents a particular directory state
-of a working directory, a "commit" represents that state in "time",
+of a working directory, a "commit" represents that state in time,
 and explains how we got there.
 
 You create a commit object by giving it the tree that describes the

-- 
1.8.3.msysgit.0


---
Thomas

Combine the two cases for "git add" into one.
Add verb "use" to "git rm" case.

Signed-off-by: Thomas Ackermann <redacted>
---
 Documentation/user-manual.txt | 11 +++--------
 1 file changed, 3 insertions(+), 8 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 8a1a441..ca78333 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt

@@ -1080,19 +1080,14 @@ produce no output at that point.
 
 Modifying the index is easy:
 
-To update the index with the new contents of a modified file, use
+To add the contents of a new file to the index or update the index 
+with the new contents of a modified file, use
 
 -------------------------------------------------
 $ git add path/to/file
 -------------------------------------------------
 
-To add the contents of a new file to the index, use
-
--------------------------------------------------
-$ git add path/to/file
--------------------------------------------------
-
-To remove a file from the index and from the working tree,
+To remove a file from the index and from the working tree, use
 
 -------------------------------------------------
 $ git rm path/to/file

-- 
1.8.3.msysgit.0


---
Thomas

Describe the conflict resolution in terms of the
commands the user is supposed to use.

Signed-off-by: Thomas Ackermann <redacted>
---
 Documentation/user-manual.txt | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index ccbddc7..0656191 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt

@@ -1251,10 +1251,8 @@ Automatic merge failed; fix conflicts and then commit the result.
 -------------------------------------------------
 
 Conflict markers are left in the problematic files, and after
-you resolve the conflicts manually, you can update the index
-with the contents and run Git commit, as you normally would when
-creating a new file.
-
+you have resolved the conflicts manually, you can `git add` the
+new contents and do a `git commit` in the end.
 If you examine the resulting commit using gitk, you will see that it
 has two parents, one pointing to the top of the current branch, and
 one to the top of the other branch.

-- 
1.8.3.msysgit.0


---
Thomas

Add some missing punctuation.
Simplify description of "git branch -d/-D".

Signed-off-by: Thomas Ackermann <redacted>
---
 Documentation/user-manual.txt | 19 +++++++------------
 1 file changed, 7 insertions(+), 12 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 0656191..d5baf03 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt

@@ -268,27 +268,22 @@ Creating, deleting, and modifying branches is quick and easy; here's
 a summary of the commands:
 
 `git branch`::
-	list all branches
+	list all branches.
 `git branch <branch>`::
 	create a new branch named `<branch>`, referencing the same
-	point in history as the current branch
+	point in history as the current branch.
 `git branch <branch> <start-point>`::
 	create a new branch named `<branch>`, referencing
 	`<start-point>`, which may be specified any way you like,
-	including using a branch name or a tag name
+	including using a branch name or a tag name.
 `git branch -d <branch>`::
-	delete the branch `<branch>`; if the branch you are deleting
-	points to a commit which is not reachable from the current
-	branch, this command will fail with a warning.
+	delete the branch `<branch>`; if the branch is not fully
+	merged in its upstream branch, this command will fail with a warning.
 `git branch -D <branch>`::
-	even if the branch points to a commit not reachable
-	from the current branch, you may know that that commit
-	is still reachable from some other branch or tag.  In that
-	case it is safe to use this command to force Git to delete
-	the branch.
+	delete the branch `<branch>` irrespective of its merged status.
 `git checkout <branch>`::
 	make the current branch `<branch>`, updating the working
-	directory to reflect the version referenced by `<branch>`
+	directory to reflect the version referenced by `<branch>`.
 `git checkout -b <new> <start-point>`::
 	create a new branch `<new>` referencing `<start-point>`, and
 	check it out.

-- 
1.8.3.msysgit.0


---
Thomas

Remove unnecessary quoting.
Simplify description of three-way merge.

Signed-off-by: Thomas Ackermann <redacted>
---
 Documentation/user-manual.txt | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index d5baf03..f713f26 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt

@@ -3992,16 +3992,16 @@ Merging multiple trees
 
 Git helps you do a three-way merge, which you can expand to n-way by
 repeating the merge procedure arbitrary times until you finally
-"commit" the state.  The normal situation is that you'd only do one
+commit the state.  The normal situation is that you'd only do one
 three-way merge (two parents), and commit it, but if you like to, you
 can do multiple parents in one go.
 
-To do a three-way merge, you need the two sets of "commit" objects
+To do a three-way merge, you need the two commit objects
 that you want to merge, use those to find the closest common parent (a
-third "commit" object), and then use those commit objects to find the
-state of the directory ("tree" object) at these points.
+third commit object: the merge base), and then use those commit objects to find the
+state of the directory (i.e. tree object) at these points.
 
-To get the "base" for the merge, you first look up the common parent
+To get the base for the merge, you first look up the common parent
 of two commits with
 
 -------------------------------------------------

@@ -4009,8 +4009,8 @@ $ git merge-base <commit1> <commit2>
 -------------------------------------------------
 
 which will return you the commit they are both based on.  You should
-now look up the "tree" objects of those commits, which you can easily
-do with (for example)
+now look up the tree objects of those commits, which you can easily
+do with
 
 -------------------------------------------------
 $ git cat-file commit <commitname> | head -1

-- 
1.8.3.msysgit.0


---
Thomas

Signed-off-by: Thomas Ackermann <redacted>
---
 Documentation/user-manual.txt | 2 --
 1 file changed, 2 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index f713f26..aa6bfab 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt

@@ -4132,8 +4132,6 @@ about the data in the object.  It's worth noting that the SHA-1 hash
 that is used to name the object is the hash of the original data
 plus this header, so `sha1sum` 'file' does not match the object name
 for 'file'.
-(Historical note: in the dawn of the age of Git the hash
-was the SHA-1 of the 'compressed' object.)
 
 As a result, the general consistency of an object can always be tested
 independently of the contents or the type of the object: all objects can

-- 
1.8.3.msysgit.0


---
Thomas

Signed-off-by: Thomas Ackermann <redacted>
---
 Documentation/user-manual.txt | 2 --
 1 file changed, 2 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index aa6bfab..0d3f04e 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt

@@ -2131,8 +2131,6 @@ He uses two public branches:
 
  - A "test" tree into which patches are initially placed so that they
    can get some exposure when integrated with other ongoing development.
-   This tree is available to Andrew for pulling into -mm whenever he
-   wants.
 
  - A "release" tree into which tested patches are moved for final sanity
    checking, and as a vehicle to send them upstream to Linus (by sending

-- 
1.8.3.msysgit.0


---
Thomas

Sorry Jon, but this might not be of any help to new Git users ;)

Signed-off-by: Thomas Ackermann <redacted>
---
 Documentation/user-manual.txt | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 0d3f04e..08d8c91 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt

@@ -3908,8 +3908,7 @@ save the note about that state, in practice we tend to just write the
 result to the file pointed at by `.git/HEAD`, so that we can always see
 what the last committed state was.
 
-Here is an ASCII art by Jon Loeliger that illustrates how
-various pieces fit together.
+Here is a picture that illustrates how various pieces fit together:
 
 ------------
 

-- 
1.8.3.msysgit.0


---
Thomas

According to the man-pages of "git prune" and "git fsck",
both are safe nowadays.

Signed-off-by: Thomas Ackermann <redacted>
---
 Documentation/user-manual.txt | 12 +-----------
 1 file changed, 1 insertion(+), 11 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 08d8c91..29945d9 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt

@@ -3283,17 +3283,7 @@ state, you can just prune all unreachable objects:
 $ git prune
 ------------------------------------------------
 
-and they'll be gone. But you should only run `git prune` on a quiescent
-repository--it's kind of like doing a filesystem fsck recovery: you
-don't want to do that while the filesystem is mounted.
-
-(The same is true of `git fsck` itself, btw, but since
-`git fsck` never actually *changes* the repository, it just reports
-on what it found, `git fsck` itself is never 'dangerous' to run.
-Running it while somebody is actually changing the repository can cause
-confusing and scary messages, but it won't actually do anything bad. In
-contrast, running `git prune` while somebody is actively changing the
-repository is a *BAD* idea).
+and they'll be gone. 
 
 [[recovering-from-repository-corruption]]
 Recovering from repository corruption

-- 
1.8.3.msysgit.0


---
Thomas

From: "Thomas Ackermann" <redacted>

Hi,

command output has changed for some commands in the last years,
so reflect this also in the user-manual. While doing so, fix some
minor
spelling, formatting and wording issues.

Further, some references and recommendations which nowadays might
only confuse and not help new Git users where removed. Also some
explanations where rephrased to IMHO make them easier to understand
for new users.

Since 1.8.3 we have had the ability to list the main Git Guides using
the 'git help -g' option, unfortunately the User Manual is not in a man
format, so it isn't listed within the help option.

Is it worth adjusting the User Manual formatting such that it could be
displayed as a man page? (which would also require a file name change
from user-manual.txt to git-user-manual.txt). Or create a new man page
helper `git-user-manual.txt` that would provide a follow-me link to the
current user manual?

Back at $gmane/216146 Junio noted that the git(1) man page does contain
onward links to the user manual, but I believe that users should be able
to get to it directly from a git command such as 'git help user-manual'.
Easy access makes it more likely to be read, in the same way that man 
pages are checked.

Philip

The last patch removes a lengthy paragraph which states that "git
prune"
(and "git fsck") should only be used in a quiescent repository.  The
man-page for "git prune" tells nothing about this. So either the
removal should be OK or we have to duplicate the warning paragraph
in the man-page of "git prune"?

[PATCH 01/13] Call it "Git User Manual" and remove reference to very
old Git version
[PATCH 02/13] Use current "detached HEAD" message
[PATCH 03/13] Use current output for "git repack"
[PATCH 04/13] Use "git merge" instead of "git pull ."
[PATCH 05/13] Fix some typos
[PATCH 06/13] Simplify "How to make a commit"
[PATCH 07/13] Improve description in "How to merge"
[PATCH 08/13] Improve section "Manipulating branches"
[PATCH 09/13] Improve section "Merge multiple trees"
[PATCH 10/13] Remove unnecessary historical note from "Object storage
format"
[PATCH 11/13] Remove obscure reference from "Examples"
[PATCH 12/13] Remove irrelevant reference from "Tying it all together"
[PATCH 13/13] "git prune" is safe now

Signed-off-by: Thomas Ackermann <redacted>


---
Thomas

Thomas Ackermann wrote:

"User" versus "User's": why?  But I don't care much about this.

Dropping the reference to 1.5.3 is very welcome, since it should help
people to update the manual without fearing that new sections will
fail for people with ancient copies of git.  For what it's worth,
Reviewed-by: Jonathan Nieder <redacted>

Thomas Ackermann wrote:

I wonder if this longer wall of text (added in 13be3e31, 2010-01-29)
is too aggressive.

It is the only piece of advice that I explicitly disable in
~/.gitconfig, so I haven't looked at it again for a while.  Since
then, the usual stream of questions about how to recover from people
who accidentally detached HEAD has still been showing up in #git, so I
don't think the message succeeded in its purpose.

That might be partly because it is too long to digest at a glance.

When I see this message, what I actually take in is

                  $ git checkout v1.7.3
 Hmm, capital --->Note: checking out 'v1.7.3'.
 heading before
 lowercase        You are in 'detached HEAD' state. You ...
 sentence.
                                                            ... checkout.

                  If you want ...
                  do so (now or later) by using -b               .... Example:

                    git ...

                  HEAD is ...
 Phew, I can ---->$
 type commands
 again.

Whereas I think the message is just meant to convey the following:

      $ git checkout v2.6.17
      note: checking out a tag for inspection and discardable experiments on top

      To create a new branch to save your changes:

            git checkout -b my-branch-based-on-v2.6.17

      HEAD is now at 427abfa... Linux v2.6.17
      $

	grep "no branch" Documentation/user-manual.txt

finds two other instances of that message, which this branch doesn't
touch.  One is about a bisection, where (no branch) is pretty close
to the actual message ('(no branch, bisect started on master)').
The other is about submodules.  Here's a patch for potential squashing
in that corrects it.

Thanks,
Jonathan

diff --git i/Documentation/user-manual.txt w/Documentation/user-manual.txt
index 3e226190..b76219ee 100644
--- i/Documentation/user-manual.txt
+++ w/Documentation/user-manual.txt

@@ -3647,7 +3647,7 @@ working on a branch.
 
 -------------------------------------------------
 $ git branch
-* (no branch)
+* (detached from d266b98)
   master
 -------------------------------------------------
 

Thomas Ackermann wrote:

[...]

-Total 6020, written 6020 (delta 4070), reused 0 (delta 0)
-Pack pack-3e54ad29d5b2e05838c75df582c65257b8d08e1c created.
+Total 6020 (delta 4070), reused 0 (delta 0)

Sure.  I wonder if there should be some text to replace the output
that mentions the pack being created, though.  E.g.:

 ------------------------------------------------
 
 You can then run

	Total 6020 (delta 4070), reused 0 (delta 0)
	------------------------------------------------

	This creates a single "pack file" in .git/objects/pack/ containing
	all currently unpacked objects.  You can then run

Thomas Ackermann wrote:

I wonder if it would make sense to say they simply *are* equivalent.
I.e., what differences are there between those two commands, and could
"git pull" be tweaked to eliminate them?

I agree that the historical "The former is actually very commonly
used" ought to go.  It wouldn't too relevant for someone learning to
use git even if it were still true. ;-)

[...]

Yes.

Hope that helps,
Jonathan

Thomas Ackermann wrote:

That's a mouthful.  I'd say

	To update the index with the contents of a new or modified file, use

[...]

-To add the contents of a new file to the index, use
-
--------------------------------------------------
-$ git add path/to/file
--------------------------------------------------
-

\o/

-To remove a file from the index and from the working tree,
+To remove a file from the index and from the working tree, use
 
 -------------------------------------------------
 $ git rm path/to/file

In git 2.0, (plain "rm" followed by) "git add" should work for this,
too.

Thomas Ackermann wrote:

Heh.  Sure.

[...]

Yes.  Here one of the references is the nickname of a remote and not a
branch, so "reachable from" reads better than "contained in" would.

I think this reads better with a capital 'O'.  (The pedant in me
likes it, too, since a colon ends a sentence.)

The lowercase 'but' later in this section should perhaps also be
capitalized, since it also starts an independent thought.

	But that may sometimes help you guess which tags come after the
	given commit.

The sentence "So, you can run something like ... then search for a
line that looks like ..." is a sequence of incomplete thoughts.  It
could be paraphrased a little to scan better:

	So, if you run something like "git show-branch e05db0fd
	v1.5.0-rc0 v1.5.0-rc1 v1.5.0-rc2"

		$ git show-branch e05db0fd v1.5.0-rc0 v1.5.0-rc1 v1.5.0-rc2
		! [e05db...

	then a line like

		+ ++ [e05db0fd] Fix warnings in ...

	shows that e05db0fd is reachable from itself, from v1.5.0-rc1,
	and from v1.5.0-rc2, and not from v1.5.0-rc0.

[...]

I'd keep the joke.

[...]

It's not really about time but about (hypothetical, possibly branched)
history, but I think your change makes it about as clear as it can be.

Thanks, and hope that helps,
Jonathan

Thomas Ackermann wrote:

Describe the conflict resolution in terms of the
commands the user is supposed to use.

[...]

Hm.  It's been too long since I was a novice, since I find the above
clear already.

To make the text clearer, I think it would be best to *add* an example
instead of replacing it by one.

Thanks,
Jonathan

Thomas Ackermann wrote:

The above sentence is unclear to me both before and after this change.

Git helps me do a three-way merge, but I'm on my own if I want to
expand to n-way?  Those times I repeat it are arbitrary times, not
arbitrarily many times?  Using "git merge" I make commits, but I
do not finally commit to the result until the (n-1)st?  And what is
this state I am committing?

Maybe the intent is

	Git can help you perform a three-way merge, which can in turn be
	used for a many-way merge by repeating the merge procedure several
	times.  The usual situation is that you only do one three-way merge
	(reconciling two lines of history) and commit the result, but if
	you like to, you can merge several branches in one go.

	To perform a three-way merge, you start with the two commits you
	want to merge, find their closest common parent (a third commit),
	and compare the trees corresponding to these three commits.

	To get the "base" for the merge, look up the common parent of two
	commits:

		$ git merge-base <commit1> <commit2>

	This prints the name of a commit they are both based on.
	...

[...]

-To get the "base" for the merge, you first look up the common parent
+To get the base for the merge, you first look up the common parent

Merge base hasn't been defined, so this is using quotes to point out
that it is defining a new, unfamiliar term.

[...]

-now look up the "tree" objects of those commits, which you can easily
-do with (for example)
+now look up the tree objects of those commits, which you can easily
+do with

Yes.

Thomas Ackermann wrote:

This drops useful information (namely, that Tony was publishing
history for two people to consume).  Perhaps it should spell out "the
bleeding-edge -mm tree"?

Jonathan

On Sat, Aug 24, 2013 at 9:19 PM, Jonathan Nieder [off-list ref] wrote:

Thomas Ackermann wrote:

quoted

--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt

@@ -1784,17 +1784,6 @@ repository that you pulled from.
 <<fast-forwards,fast-forward>>; instead, your branch will just be
 updated to point to the latest commit from the upstream branch.)

-The `git pull` command can also be given `.` as the "remote" repository,
-in which case it just merges in a branch from the current repository; so
-the commands
-
--------------------------------------------------
-$ git pull . branch
-$ git merge branch
--------------------------------------------------
-
-are roughly equivalent.  The former is actually very commonly used.
-

I wonder if it would make sense to say they simply *are* equivalent.
I.e., what differences are there between those two commands, and could
"git pull" be tweaked to eliminate them?

One difference is that "git pull" can be configured to rebase.

[...]

quoted

@@ -2259,7 +2248,7 @@ When you are happy with the state of this change, you can pull it into the
 "test" branch in preparation to make it public:

I realize that "pull" here is not necessarily about the command, but
perhaps it would still make sense to change it?

I wonder if this longer wall of text (added in 13be3e31, 2010-01-29)
is too aggressive.

It is the only piece of advice that I explicitly disable in
~/.gitconfig, so I haven't looked at it again for a while.  Since
then, the usual stream of questions about how to recover from people
who accidentally detached HEAD has still been showing up in #git, so I
don't think the message succeeded in its purpose.

I like the message :-) But of course without really knowing how a
"detached HEAD" looks like in the object store, people might feel
unsure about what to do next.

	grep "no branch" Documentation/user-manual.txt

finds two other instances of that message, which this branch doesn't
touch.  One is about a bisection, where (no branch) is pretty close
to the actual message ('(no branch, bisect started on master)').
The other is about submodules.  Here's a patch for potential squashing
in that corrects it.

Thanks for spotting this!


---
Thomas

Sure.  I wonder if there should be some text to replace the output
that mentions the pack being created, though.  E.g.:

quoted

 ------------------------------------------------
 
 You can then run

	Total 6020 (delta 4070), reused 0 (delta 0)
	------------------------------------------------

	This creates a single "pack file" in .git/objects/pack/ containing
	all currently unpacked objects.  You can then run

OK; thanks! I will add this.

---
Thomas

quoted

 
-Or you can use linkgit:git-name-rev[1], which will give the commit a
+or you can use linkgit:git-name-rev[1], which will give the commit a

I think this reads better with a capital 'O'.  (The pedant in me
likes it, too, since a colon ends a sentence.)

The lowercase 'but' later in this section should perhaps also be
capitalized, since it also starts an independent thought.

	But that may sometimes help you guess which tags come after the
	given commit.

I am no native speaker, but I am a little reluctant to start a new sentence
with "But" or "Or". 

The sentence "So, you can run something like ... then search for a
line that looks like ..." is a sequence of incomplete thoughts.  It
could be paraphrased a little to scan better:

	So, if you run something like "git show-branch e05db0fd
	v1.5.0-rc0 v1.5.0-rc1 v1.5.0-rc2"

		$ git show-branch e05db0fd v1.5.0-rc0 v1.5.0-rc1 v1.5.0-rc2
		! [e05db...

	then a line like

		+ ++ [e05db0fd] Fix warnings in ...

	shows that e05db0fd is reachable from itself, from v1.5.0-rc1,
	and from v1.5.0-rc2, and not from v1.5.0-rc0.

OK; thanks! I will add this.

quoted

 
-To see how submodule support works, create (for example) four example
+To see how submodule support works, create four example

I'd keep the joke.

I totally missed the joke ...


---
Thomas

That's a mouthful.  I'd say

	To update the index with the contents of a new or modified file, use

OK; thanks! I will change this.


---
Thomas

quoted

 
  - A "test" tree into which patches are initially placed so that they
    can get some exposure when integrated with other ongoing development.
-   This tree is available to Andrew for pulling into -mm whenever he
-   wants.

This drops useful information (namely, that Tony was publishing
history for two people to consume).  Perhaps it should spell out "the
bleeding-edge -mm tree"?

This is even worse for me;-) For everyone not involved in Linux kernel development
this sentence completely makes no sense. Is there perhaps a more general
description for the situation?


---
Thomas

Hm.  It's been too long since I was a novice, since I find the above
clear already.

OK; I will drop that patch.


---
Thomas

Maybe the intent is

	Git can help you perform a three-way merge, which can in turn be
	used for a many-way merge by repeating the merge procedure several
	times.  The usual situation is that you only do one three-way merge
	(reconciling two lines of history) and commit the result, but if
	you like to, you can merge several branches in one go.

	To perform a three-way merge, you start with the two commits you
	want to merge, find their closest common parent (a third commit),
	and compare the trees corresponding to these three commits.

	To get the "base" for the merge, look up the common parent of two
	commits:

		$ git merge-base <commit1> <commit2>

	This prints the name of a commit they are both based on.
	...

Thanks! Your text is much better than the original one (and my small changes didn't
even try to improve the text per se). 
If you don't mind I will use your text and add your sign-off for this patch.



---
Thomas

Thomas Ackermann wrote:

quoted

Maybe the intent is

	Git can help you perform a three-way merge, which can in turn be

[...]

If you don't mind I will use your text

No problem.
Signed-off-by: Jonathan Nieder <redacted>