Re: [PATCH 08/10] user-manual.txt: explain better the remote(-tracking) branch terms

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Oct 28, 2010, 19:42 UTC
Message-ID: <20101028194252.GF14212@burratino>
In-Reply-To: <1288290117-6734-9-git-send-email-Matthieu.Moy@imag.fr>

Matthieu Moy wrote:

> Now that the documentation is mostly consistant in the use of "remote
> branch" Vs "remote-tracking branch"

In fact, I think this patch would be useful even before the documentation is perfectly consistent.

> , let's make this distinction explicit
> early in the user-manual.

Thanks.  It is good to maintain a clear vocabulary.

All that follows are nitpicks.

Show 26 quoted lines

> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -341,30 +342,38 @@ $ git branch -r
>  Examining branches from a remote repository
>  -------------------------------------------
>
>  The "master" branch that was created at the time you cloned is a copy
>  of the HEAD in the repository that you cloned from.  That repository
>  may also have had other branches, though, and your local repository
>  keeps branches which track each of those remote branches, which you
>  can view using the "-r" option to linkgit:git-branch[1]:
>
>  ------------------------------------------------
>  $ git branch -r
>    origin/HEAD
>    origin/html
>    origin/maint
>    origin/man
>    origin/master
>    origin/next
>    origin/pu
>    origin/todo
>  ------------------------------------------------
>
> +In this case, "origin" is called a remote repository, or "remote" for
> +short.

"In this case" seems redundant (since we did not explain what other case it is being opposed to). "origin" has not been explained yet. Maybe something along these lines (sorry for my poor wording)

 The repository of origin is called a remote repository, or a "remote" for
 short.

would improve it?

>         The branches of this repository are called "remote branches"
> +from our point of view. The remote-tracking branches are created in
> +the local repository at clone time, as a copy of the remote branches.

Sentence structure.  Maybe

          The branches of this repository are called "remote branches"
  from our point of view. The remote-tracking branches listed above
  were created based on the remote branches at clone time and will be
  updated by "git fetch" and "git push".
  See <<Updating -a-repository-With-git-fetch>> for details.

Show 14 quoted lines

> +They are references that will be updated by "git fetch" (hence by "git
> +pull"), and by "git push". See
> +<<Updating-a-repository-With-git-fetch>> for details.
> +
>  You cannot check out these remote-tracking branches, but you can
>  examine them on a branch of your own, just as you would a tag:
>
>  ------------------------------------------------
>  $ git checkout -b my-todo-copy origin/todo
>  ------------------------------------------------
>
>  Note that the name "origin" is just the name that git uses by default
>  to refer to the repository that you cloned from.
> @@ -1716,14 +1725,19 @@ one step:

[...]

Show 8 quoted lines

>  -------------------------------------------------
>  $ git pull
>  -------------------------------------------------
>  
> +This command will fetch the changes from the remote branches to your
> +remote-tracking branches `origin/*`, and merge default branch in the
> +current branch.
> +

Article use.  Probably something like

	s/the changes/changes/
	s/merge default branch in/merge the default branch into/

would do.