Re: [PATCH 2/2] Documentation/branch: briefly explain what a branch is

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 31, 2011, 02:51 UTC
Message-ID: <7v4o8pbxb4.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20110130213510.GC10039@burratino>

Jonathan Nieder <jrnieder@gmail.com> writes:

Show 14 quoted lines

> The new reader might not know what git refs are, that history is a
> graph, the distinction between local, remote-tracking, and remote
> branches, or how to visualize what is going on.  After this change,
> those things are still probably not evident but at least there is an
> early reminder of some of it.
>
> Also explain how to create a branch before explaining how to list
> them.  Based roughly on the description of v0.99.1~53 (Add "git
> branch" script, 2005-07-11).
>
> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
> ---
>  Documentation/git-branch.txt |   35 ++++++++++++++++++++---------------
>  1 files changed, 20 insertions(+), 15 deletions(-)

I think these two are good readability changes.  Just a few nits though.

Show 12 quoted lines

> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index d3eeb94..abad7ba 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -18,6 +18,26 @@ SYNOPSIS
>  DESCRIPTION
>  -----------
>  
> +Branches are references to commit objects, representing the tip of a
> +line of history.  The branch you are working on is referred to
> +by HEAD and the corresponding reference is updated each time
> +linkgit:git-commit[1] or linkgit:git-merge[1] makes a new commit.

I think "makes a new commit" is a somewhat misleading thing to say (think "fast forward" or "rebase that makes more than one"). The important point is "advances your history", isn't it? How about...

	... reference is updated with various operations that advance your
	history, e.g. linkgit:git-commit[1], linkgit:git-pull[1], etc.

Obviously we do not want to be exhausitve, so I tried to reword the above in a way that makes it explicit that we are not trying to be.

Show 7 quoted lines

> +'git branch' <branchname> [<start-point>]::
> +	Creates a new branch named `<branchname>`.
> +	If a starting point is specified, that will be where the branch
> +	is created; otherwise, the new branch points to the `HEAD` commit.
> ++
> +This will create a new branch, but it does not switch the working tree
> +to it.  Use "git checkout <newbranch>" to start working on the new branch.

I do not think we define what _switch_ means to explain "it does not switch the working tree to it" anywhere in the glossary.

The operation not only "does not switcfh the working tree", but also does not do anything to HEAD. You and I know that, but a new reader might not, and especially after hearing that "branch ... is referred to by HEAD", might get a wrong impression that branch creation may do something to HEAD.

Perhaps...

	This only creates a new branch; you are still on the same branch
	you were on before.  If you want to start working on the new
	branch, say "git checkout <newbranch>".

might be less confusing (we might also want to hint "checkout -b").

Thanks.