patch, 13 partsModernize user-manual

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

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

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

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

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

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

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

> 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

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

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

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

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

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

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

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

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

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

> 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

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

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

> 
> That's a mouthful.  I'd say
> 
> 	To update the index with the contents of a new or modified file, use
> 

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

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

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

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

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

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

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

> 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

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

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

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

> 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

> 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