[PATCH 0/9] Documentation tweaks

[PATCH 0/9] Documentation tweaks

[Jonathan Nieder]

Hi gitsters,

Here are some small documentation patches that have been sitting in
my tree for a while.  Most important is the first one, which makes it
easier to find the appropriate options for building documentation
from source on a new machine.

Perhaps they could be of some use.  I look forward to your thoughts.

Jonathan Nieder (9):
  Describe DOCBOOK_XSL_172, ASCIIDOC_NO_ROFF options in Makefile
  Documentation: git fmt-merge-message is not a script
  Documentation: fix singular/plural mismatch
  Documentation: say "the same" instead of "equal"
  Documentation: clone: clarify discussion of initial branch
  Documentation: branch: update --merged description
  Documentation: clarify branch creation
  Documentation: clarify "working tree" definition
  racy-git.txt: explain nsec problem in more detail

 Documentation/config.txt             |    2 +-
 Documentation/git-branch.txt         |   27 ++++++++++++++++-----------
 Documentation/git-clone.txt          |    3 ++-
 Documentation/git-fmt-merge-msg.txt  |    2 +-
 Documentation/git-merge.txt          |   11 ++++++-----
 Documentation/glossary-content.txt   |    6 +++---
 Documentation/technical/racy-git.txt |   10 ++++++----
 Makefile                             |    6 +++++-
 8 files changed, 40 insertions(+), 27 deletions(-)

[PATCH 1/9] Describe DOCBOOK_XSL_172, ASCIIDOC_NO_ROFF options in Makefile

[Jonathan Nieder]

There is excellent documentation for these options in
Documentation/Makefile, but some users may never find it.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Makefile |    6 +++++-
 1 files changed, 5 insertions(+), 1 deletions(-)

diff --git a/Makefile b/Makefile
index dd3d520..929d592 100644
--- a/Makefile
+++ b/Makefile
@@ -153,7 +153,11 @@ all::
 #
 # Define ASCIIDOC8 if you want to format documentation with AsciiDoc 8
 #
-# Define DOCBOOK_XSL_172 if you want to format man pages with DocBook XSL v1.72.
+# Define DOCBOOK_XSL_172 if you want to format man pages with DocBook XSL v1.72
+# (not v1.73 or v1.71).
+#
+# Define ASCIIDOC_NO_ROFF if your DocBook XSL escapes raw roff directives
+# (versions 1.72 and later and 1.68.1 and earlier).
 #
 # Define NO_PERL_MAKEMAKER if you cannot use Makefiles generated by perl's
 # MakeMaker (e.g. using ActiveState under Cygwin).
-- 
1.6.5.rc1.199.g596ec

[PATCH 2/9] Documentation: git fmt-merge-message is not a script

[Jonathan Nieder]

The fmt-merge-message builtin is usually invoked as
"git fmt-merge-message" rather than through the hard link in
GIT_EXEC_PATH.  Although this is unlikely to confuse most script
writers, it should not hurt to make the documentation a little
clearer anyway.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-fmt-merge-msg.txt |    2 +-
 Documentation/git-merge.txt         |    7 ++++---
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt
index 1c24796..0067805 100644
--- a/Documentation/git-fmt-merge-msg.txt
+++ b/Documentation/git-fmt-merge-msg.txt
@@ -18,7 +18,7 @@ Takes the list of merged objects on stdin and produces a suitable
 commit message to be used for the merge commit, usually to be
 passed as the '<merge-message>' argument of 'git-merge'.
 
-This script is intended mostly for internal use by scripts
+This command is intended mostly for internal use by scripts
 automatically invoking 'git-merge'.
 
 OPTIONS
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index af68d69..354e9d9 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -28,9 +28,10 @@ OPTIONS
 include::merge-options.txt[]
 
 -m <msg>::
-	The commit message to be used for the merge commit (in case
-	it is created). The 'git-fmt-merge-msg' script can be used
-	to give a good default for automated 'git-merge' invocations.
+	Set the commit message to be used for the merge commit (in
+	case one is created). The 'fmt-merge-msg' Git command can be
+	used to give a good default for automated 'git-merge'
+	invocations.
 
 <remote>...::
 	Other branch heads to merge into our branch.  You need at
-- 
1.6.5.rc1.199.g596ec

[PATCH 3/9] Documentation: fix singular/plural mismatch

[Jonathan Nieder]

Sounds better this way, at least to my ears.  ("syntax and
supported options of git merge" is a plural noun.)

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/config.txt    |    2 +-
 Documentation/git-merge.txt |    2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index be0b8ca..4d01dde 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -539,7 +539,7 @@ branch.<name>.merge::
 
 branch.<name>.mergeoptions::
 	Sets default options for merging into branch <name>. The syntax and
-	supported options are equal to that of linkgit:git-merge[1], but
+	supported options are equal to those of linkgit:git-merge[1], but
 	option values containing whitespace characters are currently not
 	supported.
 
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 354e9d9..6da07bb 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -50,7 +50,7 @@ include::merge-config.txt[]
 
 branch.<name>.mergeoptions::
 	Sets default options for merging into branch <name>. The syntax and
-	supported options are equal to that of 'git-merge', but option values
+	supported options are equal to those of 'git-merge', but option values
 	containing whitespace characters are currently not supported.
 
 HOW MERGE WORKS
-- 
1.6.5.rc1.199.g596ec

[PATCH 4/9] Documentation: say "the same" instead of "equal"

[Jonathan Nieder]

When non-mathematical objects are declared equal in documentation,
this is a sign that perhaps the discussion is becoming too
technical or exact.  Use "same" instead if no other nuance is
required.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/config.txt    |    2 +-
 Documentation/git-merge.txt |    4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 4d01dde..cd17814 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -539,7 +539,7 @@ branch.<name>.merge::
 
 branch.<name>.mergeoptions::
 	Sets default options for merging into branch <name>. The syntax and
-	supported options are equal to those of linkgit:git-merge[1], but
+	supported options are the same as those of linkgit:git-merge[1], but
 	option values containing whitespace characters are currently not
 	supported.
 
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 6da07bb..6ffd4b0 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -50,8 +50,8 @@ include::merge-config.txt[]
 
 branch.<name>.mergeoptions::
 	Sets default options for merging into branch <name>. The syntax and
-	supported options are equal to those of 'git-merge', but option values
-	containing whitespace characters are currently not supported.
+	supported options are the same as those of 'git-merge', but option
+	values containing whitespace characters are currently not supported.
 
 HOW MERGE WORKS
 ---------------
-- 
1.6.5.rc1.199.g596ec

[PATCH 3-4/9 v2] Documentation: clarify mergeoptions description

[Jonathan Nieder]

Sounds better this way, at least to my ears.  ("The syntax and
supported options of git merge" is a plural noun.  "the same"
instead of "equal" sounds less technical and seems to convey
the meaning better here.)

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
Sean Estabrooks wrote:

> P.S.  Patches 3 and 4 in this series would be better as a single patch.

Good idea.  Here's a squashed version.

 Documentation/config.txt    |    2 +-
 Documentation/git-merge.txt |    4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index be0b8ca..cd17814 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -539,7 +539,7 @@ branch.<name>.merge::
 
 branch.<name>.mergeoptions::
 	Sets default options for merging into branch <name>. The syntax and
-	supported options are equal to that of linkgit:git-merge[1], but
+	supported options are the same as those of linkgit:git-merge[1], but
 	option values containing whitespace characters are currently not
 	supported.
 
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 354e9d9..6ffd4b0 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -50,8 +50,8 @@ include::merge-config.txt[]
 
 branch.<name>.mergeoptions::
 	Sets default options for merging into branch <name>. The syntax and
-	supported options are equal to that of 'git-merge', but option values
-	containing whitespace characters are currently not supported.
+	supported options are the same as those of 'git-merge', but option
+	values containing whitespace characters are currently not supported.
 
 HOW MERGE WORKS
 ---------------
-- 
1.6.5.rc1.199.g596ec

[PATCH 5/9] Documentation: clone: clarify discussion of initial branch

[Jonathan Nieder]

When saying the initial branch is equal to the currently active
remote branch, it is probably intended that the branch heads
point to the same commit.  Maybe it would be more useful to a new
user to emphasize that the tree contents and history are the
same.

More important, probably, is that this new branch is set up so
that "git pull" merges changes from the corresponding remote
branch.  The next paragraph addresses that directly, but
clarifying the initial content of the branch should make it
clearer why a pull is required at all (that local and remote
branches each have their own history after the clone).

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-clone.txt |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index aacf4fd..7cd06e2 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -20,7 +20,8 @@ DESCRIPTION
 Clones a repository into a newly created directory, creates
 remote-tracking branches for each branch in the cloned repository
 (visible using `git branch -r`), and creates and checks out an initial
-branch equal to the cloned repository's currently active branch.
+branch with the contents of the cloned repository's currently active
+branch.
 
 After the clone, a plain `git fetch` without arguments will update
 all the remote-tracking branches, and a `git pull` without
-- 
1.6.5.rc1.199.g596ec

Re: [PATCH 5/9] Documentation: clone: clarify discussion of initial branch

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> When saying the initial branch is equal to the currently active
> remote branch, it is probably intended that the branch heads
> point to the same commit.  Maybe it would be more useful to a new
> user to emphasize that the tree contents and history are the
> same.
>
> More important, probably, is that this new branch is set up so
> that "git pull" merges changes from the corresponding remote
> branch.

All true, and "with the contents of" is dropping the "history" part.
Perhaps

    ... creates and checks out an initial branch that is forked from the
    cloned repository's currently active branch.

would convey that (1) the initial branch is your own; if you do not pull,
you won't get updated, and that (2) the initial branch starts out at the
same commit as the upstream.

> clarifying the initial content of the branch should make it
> clearer why a pull is required at all (that local and remote
> branches each have their own history after the clone).
>
> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
> ---
>  Documentation/git-clone.txt |    3 ++-
>  1 files changed, 2 insertions(+), 1 deletions(-)
>
> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> index aacf4fd..7cd06e2 100644
> --- a/Documentation/git-clone.txt
> +++ b/Documentation/git-clone.txt
> @@ -20,7 +20,8 @@ DESCRIPTION
>  Clones a repository into a newly created directory, creates
>  remote-tracking branches for each branch in the cloned repository
>  (visible using `git branch -r`), and creates and checks out an initial
> -branch equal to the cloned repository's currently active branch.
> +branch with the contents of the cloned repository's currently active
> +branch.
>  
>  After the clone, a plain `git fetch` without arguments will update
>  all the remote-tracking branches, and a `git pull` without
> -- 
> 1.6.5.rc1.199.g596ec
>
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 5/9 v2] Documentation: clone: clarify discussion of initial branch

[Jonathan Nieder]

When saying the initial branch is equal to the currently active
remote branch, it is probably intended that the branch heads
point to the same commit.  Maybe it would be more useful to a
new user to emphasize that the tree contents and history are the
same.

More important, probably, is that this new branch is set up so
that "git pull" merges changes from the corresponding remote
branch.  The next paragraph addresses that directly.  What the
reader needs to know to begin with is that (1) the initial branch
is your own; if you do not pull, it won't get updated, and that
(2) the initial branch starts out at the same commit as the
upstream.

Thanks to Junio C Hamano for the wording.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
Junio C Hamano wrote:

> Perhaps
> 
>     ... creates and checks out an initial branch that is forked from the
>     cloned repository's currently active branch.
> 
> would convey that (1) the initial branch is your own; if you do not pull,
> you won't get updated, and that (2) the initial branch starts out at the
> same commit as the upstream.

That does work better.  Explanation stolen for the commit message ---
I hope you don't mind.

Thanks,
Jonathan

 Documentation/git-clone.txt |    5 +++--
 1 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index aacf4fd..5ebcba1 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -19,8 +19,9 @@ DESCRIPTION
 
 Clones a repository into a newly created directory, creates
 remote-tracking branches for each branch in the cloned repository
-(visible using `git branch -r`), and creates and checks out an initial
-branch equal to the cloned repository's currently active branch.
+(visible using `git branch -r`), and creates and checks out an
+initial branch that is forked from the cloned repository's
+currently active branch.
 
 After the clone, a plain `git fetch` without arguments will update
 all the remote-tracking branches, and a `git pull` without
-- 
1.6.5.rc1.199.g596ec

[PATCH 6/9] Documentation: branch: update --merged description

[Jonathan Nieder]

Update the documentation for --merged and --no-merged to explain
the meaning of the optional parameter introduced in commit 049716b
(branch --merged/--no-merged: allow specifying arbitrary commit,
2008-07-08).

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-branch.txt |   10 ++++++----
 1 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index aad71dc..e8b32a2 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -134,11 +134,13 @@ start-point is either a local or remote branch.
 --contains <commit>::
 	Only list branches which contain the specified commit.
 
---merged::
-	Only list branches which are fully contained by HEAD.
+--merged [<commit>]::
+	Only list branches whose tips are reachable from the
+	specified commit (HEAD if not specified).
 
---no-merged::
-	Do not list branches which are fully contained by HEAD.
+--no-merged [<commit>]::
+	Do not list branches whose tips are reachable from the
+	specified commit (HEAD if not specified).
 
 <branchname>::
 	The name of the branch to create or delete.
-- 
1.6.5.rc1.199.g596ec

Re: [PATCH 6/9] Documentation: branch: update --merged description

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Update the documentation for --merged and --no-merged to explain
> the meaning of the optional parameter introduced in commit 049716b
> (branch --merged/--no-merged: allow specifying arbitrary commit,
> 2008-07-08).
>
> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>

Thanks.

I most often use --no-merged this way:

	$ git branch --no-merged pu

to see topics that are queued but not merged anywhere.  This is not about
"do not list", but "do show the ones that are not merged", so I reworded
the description of the latter in your patch.

> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index aad71dc..e8b32a2 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -134,11 +134,13 @@ start-point is either a local or remote branch.
>  --contains <commit>::
>  	Only list branches which contain the specified commit.
>  
> ---merged::
> -	Only list branches which are fully contained by HEAD.
> +--merged [<commit>]::
> +	Only list branches whose tips are reachable from the
> +	specified commit (HEAD if not specified).
>  
> ---no-merged::
> -	Do not list branches which are fully contained by HEAD.
> +--no-merged [<commit>]::
> +	Only list branches whose tips are not reachable from the
> +	specified commit (HEAD if not specified).
>  
>  <branchname>::
>  	The name of the branch to create or delete.
> -- 
> 1.6.5.rc1.199.g596ec
>
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 7/9] Documentation: clarify branch creation

[Jonathan Nieder]

The documentation seems to assume that the starting point for a new
branch is the tip of an existing (ordinary) branch, but that is not
the most common case.  More often, "git branch" is used to begin
a branch from a remote-tracking branch, a tag, or an interesting
commit (e.g. origin/pu^2).  Clarify the language so it can apply
to these cases.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-branch.txt |   17 ++++++++++-------
 1 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index e8b32a2..990f782 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -30,10 +30,11 @@ commit) will be listed.  With `--no-merged` only branches not merged into
 the named commit will be listed.  If the <commit> argument is missing it
 defaults to 'HEAD' (i.e. the tip of the current branch).
 
-In the command's second form, a new branch named <branchname> will be created.
-It will start out with a head equal to the one given as <start-point>.
-If no <start-point> is given, the branch will be created with a head
-equal to that of the currently checked out branch.
+In the command's second form, creates a new branch named <branchname>.
+The branch will start out with head pointing to the commit
+<start-point>.  If no <start-point> is given, the branch will start
+out with head pointing to the tip of the currently checked out branch,
+or the currently checked out commit if no branch is checked out.
 
 Note that this will create the new branch, but it will not switch the
 working tree to it; use "git checkout <newbranch>" to switch to the
@@ -149,9 +150,11 @@ start-point is either a local or remote branch.
 	may restrict the characters allowed in a branch name.
 
 <start-point>::
-	The new branch will be created with a HEAD equal to this.  It may
-	be given as a branch name, a commit-id, or a tag.  If this option
-	is omitted, the current branch is assumed.
+	The new branch head will point to this commit.  It may be
+	given as a branch name, a commit-id, or a tag.  If this
+	option is omitted, the currently checked out branch head
+	is used, or the current commit if no branch is checked
+	out.
 
 <oldbranch>::
 	The name of an existing branch to rename.
-- 
1.6.5.rc1.199.g596ec

Re: [PATCH 7/9] Documentation: clarify branch creation

[Sean Estabrooks]

On Fri, 9 Oct 2009 05:19:40 -0500
Jonathan Nieder <jrnieder@gmail.com> wrote:

> +In the command's second form, creates a new branch named <branchname>.
> +The branch will start out with head pointing to the commit
> +<start-point>.  If no <start-point> is given, the branch will start
> +out with head pointing to the tip of the currently checked out branch,
> +or the currently checked out commit if no branch is checked out.

The first sentence here doesn't quite work, perhaps drop the "In".  But
the whole thing is a bit verbose, what about just:

The command's second form creates a new branch named <branchname> which
points to the current HEAD or <start-point> if given.

>  <start-point>::
> -	The new branch will be created with a HEAD equal to this.  It may
> -	be given as a branch name, a commit-id, or a tag.  If this option
> -	is omitted, the current branch is assumed.
> +	The new branch head will point to this commit.  It may be
> +	given as a branch name, a commit-id, or a tag.  If this
> +	option is omitted, the currently checked out branch head
> +	is used, or the current commit if no branch is checked
> +	out.

Maybe it's not worth worrying about, but couldn't the last sentence
be just:

   If this option is omitted, the current HEAD will be used instead.

Sean

P.S.  Patches 3 and 4 in this series would be better as a single patch.

Re: [PATCH 7/9] Documentation: clarify branch creation

[Jonathan Nieder]

Sean Estabrooks wrote:
> On Fri, 9 Oct 2009 05:19:40 -0500
> Jonathan Nieder <jrnieder@gmail.com> wrote:
> 
> > +In the command's second form, creates a new branch named <branchname>.
> > +The branch will start out with head pointing to the commit
> > +<start-point>.  If no <start-point> is given, the branch will start
> > +out with head pointing to the tip of the currently checked out branch,
> > +or the currently checked out commit if no branch is checked out.
> 
> The first sentence here doesn't quite work, perhaps drop the "In".  But
> the whole thing is a bit verbose, what about just:
> 
> The command's second form creates a new branch named <branchname> which
> points to the current HEAD or <start-point> if given.

Makes sense.  I modified this slightly to “new branch head” since the
branch itself does not point to anything.

> >  <start-point>::
> > -	The new branch will be created with a HEAD equal to this.  It may
> > -	be given as a branch name, a commit-id, or a tag.  If this option
> > -	is omitted, the current branch is assumed.
> > +	The new branch head will point to this commit.  It may be
> > +	given as a branch name, a commit-id, or a tag.  If this
> > +	option is omitted, the currently checked out branch head
> > +	is used, or the current commit if no branch is checked
> > +	out.
> 
> Maybe it's not worth worrying about, but couldn't the last sentence
> be just:
> 
>    If this option is omitted, the current HEAD will be used instead.

That sounds better, thanks.  The reader that does not know what HEAD is
probably needs to read the relevant section of the user manual for other
reasons anyway.

So this page should probably point to the what-is-a-branch section of
the User's Manual.  Maybe something like this?

-- %< --
Subject: Documentation: clarify branch creation

The documentation seems to assume that the starting point for a new
branch is the tip of an existing (ordinary) branch, but that is not
the most common case.  More often, "git branch" is used to begin
a branch from a remote-tracking branch, a tag, or an interesting
commit (e.g. origin/pu^2).  Clarify the language so it can apply
to these cases.  Thanks to Sean Estabrooks for the wording.

Also add a pointer to the user's manual for the bewildered.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-branch.txt |   16 ++++++++--------
 1 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index e8b32a2..f766b4d 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -30,10 +30,8 @@ commit) will be listed.  With `--no-merged` only branches not merged into
 the named commit will be listed.  If the <commit> argument is missing it
 defaults to 'HEAD' (i.e. the tip of the current branch).
 
-In the command's second form, a new branch named <branchname> will be created.
-It will start out with a head equal to the one given as <start-point>.
-If no <start-point> is given, the branch will be created with a head
-equal to that of the currently checked out branch.
+The command's second form creates a new branch head named <branchname>
+which points to the current 'HEAD', or <start-point> if given.
 
 Note that this will create the new branch, but it will not switch the
 working tree to it; use "git checkout <newbranch>" to switch to the
@@ -149,9 +147,9 @@ start-point is either a local or remote branch.
 	may restrict the characters allowed in a branch name.
 
 <start-point>::
-	The new branch will be created with a HEAD equal to this.  It may
-	be given as a branch name, a commit-id, or a tag.  If this option
-	is omitted, the current branch is assumed.
+	The new branch head will point to this commit.  It may be
+	given as a branch name, a commit-id, or a tag.  If this
+	option is omitted, the current HEAD will be used instead.
 
 <oldbranch>::
 	The name of an existing branch to rename.
@@ -216,7 +214,9 @@ SEE ALSO
 --------
 linkgit:git-check-ref-format[1],
 linkgit:git-fetch[1],
-linkgit:git-remote[1].
+linkgit:git-remote[1],
+link:user-manual.html#what-is-a-branch[``Understanding history: What is
+a branch?''] in the Git User's Manual.
 
 Author
 ------
-- 
1.6.5.rc1.199.g596ec

Re: [PATCH 7/9] Documentation: clarify branch creation

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> So this page should probably point to the what-is-a-branch section of
> the User's Manual.  Maybe something like this?

Sounds good.  Thanks

> -- %< --
> Subject: Documentation: clarify branch creation
>
> The documentation seems to assume that the starting point for a new
> branch is the tip of an existing (ordinary) branch, but that is not
> the most common case.  More often, "git branch" is used to begin
> a branch from a remote-tracking branch, a tag, or an interesting
> commit (e.g. origin/pu^2).  Clarify the language so it can apply
> to these cases.  Thanks to Sean Estabrooks for the wording.
>
> Also add a pointer to the user's manual for the bewildered.
> ...

[PATCH 8/9] Documentation: clarify "working tree" definition

[Jonathan Nieder]

It is not necessarily obvious to a git novice what it means for a
filesystem tree to be equal to the HEAD.  Spell it out.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/glossary-content.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index 572374f..43d84d1 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -456,6 +456,6 @@ This commit is referred to as a "merge commit", or sometimes just a
 	of 'A' is 'origin/B' sometimes we say "'A' is tracking 'origin/B'".
 
 [[def_working_tree]]working tree::
-	The tree of actual checked out files.  The working tree is
-	normally equal to the <<def_HEAD,HEAD>> plus any local changes
-	that you have made but not yet committed.
+	The tree of actual checked out files.  The working tree normally
+	contains the contents of the <<def_HEAD,HEAD>> commit's tree,
+	plus any local changes that you have made but not yet committed.
-- 
1.6.5.rc1.199.g596ec

[PATCH 9/9] racy-git.txt: explain nsec problem in more detail

[Jonathan Nieder]

Idealists may want USE_NSEC to be the default on Linux some day.
Point to a patch to better explain the requirements on
filesystem code for that to happen.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
Am I understanding the problem here correctly?  It seems to me
that ext2/3/4, tmpfs, ntfs, and so on shouldn’t have problems
with USE_NSEC, and all that is left is the monster that is
networked filesystems.

 Documentation/technical/racy-git.txt |   10 ++++++----
 1 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.txt
index 48bb97f..53aa0c8 100644
--- a/Documentation/technical/racy-git.txt
+++ b/Documentation/technical/racy-git.txt
@@ -42,10 +42,12 @@ compared, but this is not enabled by default because this member
 is not stable on network filesystems.  With `USE_NSEC`
 compile-time option, `st_mtim.tv_nsec` and `st_ctim.tv_nsec`
 members are also compared, but this is not enabled by default
-because the value of this member becomes meaningless once the
-inode is evicted from the inode cache on filesystems that do not
-store it on disk.
-
+because in-core timestamps can have finer granularity than
+on-disk timestamps, resulting in meaningless changes when an
+inode is evicted from the inode cache.  See commit 8ce13b0
+of git://git.kernel.org/pub/scm/linux/kernel/git/tglx/history.git
+([PATCH] Sync in core time granuality with filesystems,
+2005-01-04).
 
 Racy git
 --------
-- 
1.6.5.rc1.199.g596ec

Re: [PATCH 9/9] racy-git.txt: explain nsec problem in more detail

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Am I understanding the problem here correctly?

I think so ;-).

Re: [PATCH 0/9] Documentation tweaks

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Here are some small documentation patches that have been sitting in
> my tree for a while.  Most important is the first one, which makes it
> easier to find the appropriate options for building documentation
> from source on a new machine.

Thanks.