[PATCH 0/13] Modernize user-manual

[PATCH 0/13] Modernize user-manual

[Thomas Ackermann]

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 <th.acker@arcor.de>


---
Thomas

[PATCH 01/13] Call it "Git User Manual" and remove reference to very old Git version

[Thomas Ackermann]

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 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

Re: [PATCH 01/13] Call it "Git User Manual" and remove reference to very old Git version

[Jonathan Nieder]

Thomas Ackermann wrote:

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

"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 <jrnieder@gmail.com>

Re: [PATCH 01/13] Call it "Git User Manual" and remove reference to very old Git version

[Junio C Hamano]

Thomas Ackermann <th.acker@arcor.de> writes:

> Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
> ---
>  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.

Yeah, it is about time.

[PATCH 02/13] Use current "detached HEAD" message

[Thomas Ackermann]

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 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

Re: [PATCH 02/13] Use current "detached HEAD" message

[Jonathan Nieder]

Thomas Ackermann wrote:

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

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
      $

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

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

Aw: Re: [PATCH 02/13] Use current "detached HEAD" message

[Thomas Ackermann]

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

[PATCH 03/13] Use current output for "git repack"

[Thomas Ackermann]

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 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

Re: [PATCH 03/13] Use current output for "git repack"

[Jonathan Nieder]

Thomas Ackermann wrote:

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

Aw: Re: [PATCH 03/13] Use current output for "git repack"

[Thomas Ackermann]

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

OK; thanks! I will add this.

---
Thomas

[PATCH 04/13] Use "git merge" instead of "git pull ."

[Thomas Ackermann]

"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 <th.acker@arcor.de>
---
 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

Re: [PATCH 04/13] Use "git merge" instead of "git pull ."

[Junio C Hamano]

Thomas Ackermann <th.acker@arcor.de> writes:

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

I think it is probably a good idea to replace "pull ." in the two
later hunks with "merge", but the flow of the explanation reads
better if you did not touch the first hunk at all.  The section
introduced how fully-spelled "git pull origin master" works, how its
parameters can be omitted in a common case of integrating with the
branch at a remote repository you usually integrate with, and then
the hunk that you touched transitions to the local use, hinting that
your local repository is not all that special.  It is very commonly
used among people who grok that fact, and of course it still works
because we do want to support that usage ;-).

On the other hand, these later two hunks are not about explaining
"pull"; using "git merge" in the examples is more appropriate.

> Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
> ---
>  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

Re: [PATCH 04/13] Use "git merge" instead of "git pull ."

[Jonathan Nieder]

Thomas Ackermann wrote:
> --- 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?

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

[...]
> @@ -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
>  -------------------------------------------------

Yes.

Hope that helps,
Jonathan

Re: [PATCH 04/13] Use "git merge" instead of "git pull ."

[Martin von Zweigbergk]

On Sat, Aug 24, 2013 at 9:19 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:
> Thomas Ackermann wrote:
>> --- 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.

> [...]
>> @@ -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?

[PATCH 05/13] Fix some typos

[Thomas Ackermann]

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 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

Re: [PATCH 05/13] Fix some typos

[Jonathan Nieder]

Thomas Ackermann wrote:

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

Heh.  Sure.

[...]
> @@ -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

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.

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

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.

[...]
> @@ -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

I'd keep the joke.

[...]
> @@ -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.

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

Aw: Re: [PATCH 05/13] Fix some typos

[Thomas Ackermann]

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

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

[PATCH 06/13] Simplify "How to make a commit"

[Thomas Ackermann]

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

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 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

Re: [PATCH 06/13] Simplify "How to make a commit"

[Junio C Hamano]

Thomas Ackermann <th.acker@arcor.de> writes:

> Combine the two cases for "git add" into one.
> Add verb "use" to "git rm" case.
>
> Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
> ---
>  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
> --------------------------------------------------

OK.

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

Re: [PATCH 06/13] Simplify "How to make a commit"

[Jonathan Nieder]

Thomas Ackermann wrote:

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

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.

Aw: Re: [PATCH 06/13] Simplify "How to make a commit"

[Thomas Ackermann]

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

[PATCH 07/13] Improve description in "How to merge"

[Thomas Ackermann]

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

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 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

Re: [PATCH 07/13] Improve description in "How to merge"

[Junio C Hamano]

Thomas Ackermann <th.acker@arcor.de> writes:

> Describe the conflict resolution in terms of the
> commands the user is supposed to use.
>
> Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
> ---
>  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.

This is a slight documentation regression, as there are cases your
conflict resolution is a removal of the file, isn't it?

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

Re: [PATCH 07/13] Improve description in "How to merge"

[Jonathan Nieder]

Thomas Ackermann wrote:

> Describe the conflict resolution in terms of the
> commands the user is supposed to use.
[...]
> --- 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.

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

Aw: Re: [PATCH 07/13] Improve description in "How to merge"

[Thomas Ackermann]

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

[PATCH 08/13] Improve section "Manipulating branches"

[Thomas Ackermann]

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

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 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

Re: [PATCH 08/13] Improve section "Manipulating branches"

[Junio C Hamano]

Thomas Ackermann <th.acker@arcor.de> writes:

> Add some missing punctuation.
> Simplify description of "git branch -d/-D".
> ...
>  `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.

But is this correct?  I somehow thought that we check with the
current or the upstream.

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

This is an OK change.

Aw: Re: [PATCH 08/13] Improve section "Manipulating branches"

[Thomas Ackermann]

 
> 
> But is this correct?  I somehow thought that we check with the
> current or the upstream.
> 

You are correct. I will add this. Thanks.


---
Thomas

[PATCH 09/13] Improve section "Merge multiple trees"

[Thomas Ackermann]

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

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 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

Re: [PATCH 09/13] Improve section "Merge multiple trees"

[Jonathan Nieder]

Thomas Ackermann wrote:

> --- 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.
> +commit the state.

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.

Aw: Re: [PATCH 09/13] Improve section "Merge multiple trees"

[Thomas Ackermann]

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

Re: Re: [PATCH 09/13] Improve section "Merge multiple trees"

[Jonathan Nieder]

Thomas Ackermann wrote:

>> 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 <jrnieder@gmail.com>

[PATCH 10/13] Remove unnecessary historical note from "Object storage format"

[Thomas Ackermann]

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 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

Re: [PATCH 10/13] Remove unnecessary historical note from "Object storage format"

[Junio C Hamano]

Thomas Ackermann <th.acker@arcor.de> writes:

> Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
> ---
>  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 we no longer are able to read such a historical object, I think
it is OK to drop the historical note in this particular case.

Thanks.

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

[PATCH 11/13] Remove obscure reference from "Examples"

[Thomas Ackermann]

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 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

Re: [PATCH 11/13] Remove obscure reference from "Examples"

[Junio C Hamano]

Thomas Ackermann <th.acker@arcor.de> writes:

> Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
> ---
>  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

Hmm.... What part is obscure and why does this need to be removed?

Re: [PATCH 11/13] Remove obscure reference from "Examples"

[Jonathan Nieder]

Thomas Ackermann wrote:

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

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

Aw: Re: [PATCH 11/13] Remove obscure reference from "Examples"

[Thomas Ackermann]

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

[PATCH 12/13] Remove irrelevant reference from "Tying it all together"

[Thomas Ackermann]

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

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 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

Re: [PATCH 12/13] Remove irrelevant reference from "Tying it all together"

[Junio C Hamano]

Thomas Ackermann <th.acker@arcor.de> writes:

> Sorry Jon, but this might not be of any help to new Git users ;)
>
> Signed-off-by: Thomas Ackermann <th.acker@arcor.de>

Yeah, I think this is long overdue.  The drawing was taken from an
e-mail posted in a discussion, and the credit should have been given
in the commit log message, not in-text.


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

Re: [PATCH 12/13] Remove irrelevant reference from "Tying it all together"

[Jon Loeliger]

> Thomas Ackermann <th.acker@arcor.de> writes:
> 
> > Sorry Jon, but this might not be of any help to new Git users ;)
> >
> > Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
> 
> Yeah, I think this is long overdue.  The drawing was taken from an
> e-mail posted in a discussion, and the credit should have been given
> in the commit log message, not in-text.
> 
> 
> > ---
> >  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 t
> o 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:
> >  
> >  ------------

Heh.  Totally agree.  I don't need my name on *that*
bit of Git documentation.  If needed, you can find
my name on *other* Git documentation. :-)

Acked-by: Jon Loeliger <jdl@jdl.com>

jdl

[PATCH 13/13] "git prune" is safe now

[Thomas Ackermann]

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

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 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

Re: [PATCH 13/13] "git prune" is safe now

[Junio C Hamano]

Thomas Ackermann <th.acker@arcor.de> writes:

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

Safe does not have much to do with the latter.  "git fsck" has
always been safe in that it would not alter the object store, and if
you run it while you are actively creating (or pruning for that
matter) objects, it _will_ get confused.

For that matter, running "prune", even though we designed it to be
safe from concurrent accesses, deliberately on a non-quiescent
repository is not a good idea, either.  It may be a good idea to
weaken the phrasing used to discourage it, but discouraging itself
is not a bad idea.

> Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
> ---
>  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

Re: [PATCH 0/13] Modernize user-manual

[Philip Oakley]

From: "Thomas Ackermann" <th.acker@arcor.de>
> 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 <th.acker@arcor.de>
>
>
> ---
> Thomas