[PATCH v2] wording fixes in the user manual and glossary

[PATCH v2] wording fixes in the user manual and glossary

[Jeremiah Mahler]

Various minor wording fixes throughout the user manual
and glossary.

The section on "Updating a repository with git fetch" was
substantially re-worded to try and better explain `git fetch`.

Signed-off-by: Jeremiah Mahler <jmmahler@gmail.com>
---

Notes:
    From the feedback I received by Chris Packham [1] it was clear
    that my re-wording of the section "Updating a repository with git fetch"
    still wasn't quite right [1].
    
    [1]: http://marc.info/?l=git&m=140100460903936&w=2
    
    I re-worded it some more to try and emphasize the remote (upstream)
    and local aspects of `git fetch`.  Chris liked those changes better [2].
    
    [2]: http://marc.info/?l=git&m=140109062903038&w=2
    
    I expanded upon this even further.  The section on git-pull is similar
    so I tried to use that as a basis.  I also thought the relationship between
    git fetch and git pull was worthy of a short note along with a link to
    the section on git-pull.

 Documentation/glossary-content.txt |  2 +-
 Documentation/user-manual.txt      | 28 ++++++++++++++++++----------
 2 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index be0858c..4e0b971 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -1,7 +1,7 @@
 [[def_alternate_object_database]]alternate object database::
 	Via the alternates mechanism, a <<def_repository,repository>>
 	can inherit part of its <<def_object_database,object database>>
-	from another object database, which is called "alternate".
+	from another object database, which is called an "alternate".
 
 [[def_bare_repository]]bare repository::
 	A bare repository is normally an appropriately
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index d33f884..f5fd61b 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -416,14 +416,22 @@ REVISIONS" section of linkgit:gitrevisions[7].
 Updating a repository with git fetch
 ------------------------------------
 
-Eventually the developer cloned from will do additional work in her
-repository, creating new commits and advancing the branches to point
-at the new commits.
+After you clone a repository and commit a few changes of your own, you
+may wish to check the original repository for updates.
+The linkgit:git-fetch[1] command is used to update all the remote-tracking
+branches to the latest version found in those repositories.
+It will not touch any of your own branches--not even the "master"
+branch that was created during clone.
+The linkgit:git-merge[1] command can then be used to merge the changes.
+
+-------------------------------------------------
+$ git fetch
+$ git merge origin/master
+-------------------------------------------------
 
-The command `git fetch`, with no arguments, will update all of the
-remote-tracking branches to the latest version found in her
-repository.  It will not touch any of your own branches--not even the
-"master" branch that was created for you on clone.
+The linkgit:git-pull[1] command,
+<<getting-updates-With-git-pull,discussed later>>,
+performs both of these steps, a fetch followed by a merge.
 
 [[fetching-branches]]
 Fetching branches from other repositories
@@ -1811,8 +1819,8 @@ manner.
 You can then import these into your mail client and send them by
 hand.  However, if you have a lot to send at once, you may prefer to
 use the linkgit:git-send-email[1] script to automate the process.
-Consult the mailing list for your project first to determine how they
-prefer such patches be handled.
+Consult the mailing list for your project first to determine
+their requirements for submitting patches.
 
 [[importing-patches]]
 Importing patches to a project
@@ -2255,7 +2263,7 @@ $ git checkout test && git merge speed-up-spinlocks
 It is unlikely that you would have any conflicts here ... but you might if you
 spent a while on this step and had also pulled new versions from upstream.
 
-Some time later when enough time has passed and testing done, you can pull the
+Sometime later when enough time has passed and testing done, you can pull the
 same branch into the `release` tree ready to go upstream.  This is where you
 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.
-- 
2.0.0.rc4.480.gad29d77

Re: [PATCH v2] wording fixes in the user manual and glossary

[Junio C Hamano]

Jeremiah Mahler <jmmahler@gmail.com> writes:

> Various minor wording fixes throughout the user manual
> and glossary.
>
> The section on "Updating a repository with git fetch" was
> substantially re-worded to try and better explain `git fetch`.
>
> Signed-off-by: Jeremiah Mahler <jmmahler@gmail.com>
> ---
>
> Notes:
>     From the feedback I received by Chris Packham [1] it was clear
>     that my re-wording of the section "Updating a repository with git fetch"
>     still wasn't quite right [1].
>     
>     [1]: http://marc.info/?l=git&m=140100460903936&w=2
>     
>     I re-worded it some more to try and emphasize the remote (upstream)
>     and local aspects of `git fetch`.  Chris liked those changes better [2].
>     
>     [2]: http://marc.info/?l=git&m=140109062903038&w=2
>     
>     I expanded upon this even further.  The section on git-pull is similar
>     so I tried to use that as a basis.  I also thought the relationship between
>     git fetch and git pull was worthy of a short note along with a link to
>     the section on git-pull.
>
>  Documentation/glossary-content.txt |  2 +-
>  Documentation/user-manual.txt      | 28 ++++++++++++++++++----------
>  2 files changed, 19 insertions(+), 11 deletions(-)
>
> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
> index be0858c..4e0b971 100644
> --- a/Documentation/glossary-content.txt
> +++ b/Documentation/glossary-content.txt
> @@ -1,7 +1,7 @@
>  [[def_alternate_object_database]]alternate object database::
>  	Via the alternates mechanism, a <<def_repository,repository>>
>  	can inherit part of its <<def_object_database,object database>>
> -	from another object database, which is called "alternate".
> +	from another object database, which is called an "alternate".
>  
>  [[def_bare_repository]]bare repository::
>  	A bare repository is normally an appropriately
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index d33f884..f5fd61b 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -416,14 +416,22 @@ REVISIONS" section of linkgit:gitrevisions[7].
>  Updating a repository with git fetch
>  ------------------------------------
>  
> -Eventually the developer cloned from will do additional work in her
> -repository, creating new commits and advancing the branches to point
> -at the new commits.
> +After you clone a repository and commit a few changes of your own, you
> +may wish to check the original repository for updates.

The above is very good.

> +The linkgit:git-fetch[1] command is used to update all the remote-tracking
> +branches to the latest version found in those repositories.
> +It will not touch any of your own branches--not even the "master"
> +branch that was created during clone.

It is harder to review with unnecessary rewrapping of the text X-<.

I somehow feel that the original was clear around here, by being
explicit that "git fetch $there $that" is not it is talking about,
which seems to have been lost in this update.


> +The linkgit:git-merge[1] command can then be used to merge the changes.
> +
> +-------------------------------------------------
> +$ git fetch
> +$ git merge origin/master
> +-------------------------------------------------

That is not wrong per-se, but it is not a very good example.  If you
immediately merge, there is no reason not to say "git pull" in the
first place ;-)  For this to be a good example, there needs

	git log -p ..origin/master

before that merge happens, I would think.

Not that I read the text around here and confirmed that this is a
good place in the overall flow of the learning to teach about "log
-p" and "merge", though.

> @@ -1811,8 +1819,8 @@ manner.
>  You can then import these into your mail client and send them by
>  hand.  However, if you have a lot to send at once, you may prefer to
>  use the linkgit:git-send-email[1] script to automate the process.
> -Consult the mailing list for your project first to determine how they
> -prefer such patches be handled.
> +Consult the mailing list for your project first to determine
> +their requirements for submitting patches.

OK.

>  [[importing-patches]]
>  Importing patches to a project
> @@ -2255,7 +2263,7 @@ $ git checkout test && git merge speed-up-spinlocks
>  It is unlikely that you would have any conflicts here ... but you might if you
>  spent a while on this step and had also pulled new versions from upstream.
>  
> -Some time later when enough time has passed and testing done, you can pull the
> +Sometime later when enough time has passed and testing done, you can pull the

OK.