{"thread":{"id":"21167","subject":"[PATCH 0/9] Documentation tweaks","startedAt":"2009-10-09T10:14:00Z","lastAt":"2009-10-10T00:58:29Z","messageCount":19,"participants":["Jonathan Nieder","Sean Estabrooks","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":9},"messages":[{"id":"124444","messageId":"20091009101400.GA16549@progeny.tock","threadId":"21167","inReplyTo":null,"subject":"[PATCH 0/9] Documentation tweaks","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2009-10-09T10:14:00Z","receivedAt":"2009-10-09T10:14:00Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi gitsters,\n\nHere are some small documentation patches that have been sitting in\nmy tree for a while. Most important is the first one, which makes it\neasier to find the appropriate options for building documentation\nfrom source on a new machine.\n\nPerhaps they could be of some use. I look forward to your thoughts.\n\nJonathan Nieder (9):\n Describe DOCBOOK_XSL_172, ASCIIDOC_NO_ROFF options in Makefile\n Documentation: git fmt-merge-message is not a script\n Documentation: fix singular/plural mismatch\n Documentation: say \"the same\" instead of \"equal\"\n Documentation: clone: clarify discussion of initial branch\n Documentation: branch: update --merged description\n Documentation: clarify branch creation\n Documentation: clarify \"working tree\" definition\n racy-git.txt: explain nsec problem in more detail\n\n Documentation/config.txt | 2 +-\n Documentation/git-branch.txt | 27 ++++++++++++++++-----------\n Documentation/git-clone.txt | 3 ++-\n Documentation/git-fmt-merge-msg.txt | 2 +-\n Documentation/git-merge.txt | 11 ++++++-----\n Documentation/glossary-content.txt | 6 +++---\n Documentation/technical/racy-git.txt | 10 ++++++----\n Makefile | 6 +++++-\n 8 files changed, 40 insertions(+), 27 deletions(-)\n"},{"id":"124451","messageId":"20091009101529.GA16558@progeny.tock","threadId":"21167","inReplyTo":"20091009101400.GA16549@progeny.tock","subject":"[PATCH 1/9] Describe DOCBOOK_XSL_172, ASCIIDOC_NO_ROFF options in Makefile","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2009-10-09T10:15:29Z","receivedAt":"2009-10-09T10:15:29Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"There is excellent documentation for these options in\nDocumentation/Makefile, but some users may never find it.\n\nSigned-off-by: Jonathan Nieder \n---\n Makefile | 6 +++++-\n 1 files changed, 5 insertions(+), 1 deletions(-)\n\ndiff --git a/Makefile b/Makefile\nindex dd3d520..929d592 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -153,7 +153,11 @@ all::\n #\n # Define ASCIIDOC8 if you want to format documentation with AsciiDoc 8\n #\n-# Define DOCBOOK_XSL_172 if you want to format man pages with DocBook XSL v1.72.\n+# Define DOCBOOK_XSL_172 if you want to format man pages with DocBook XSL v1.72\n+# (not v1.73 or v1.71).\n+#\n+# Define ASCIIDOC_NO_ROFF if your DocBook XSL escapes raw roff directives\n+# (versions 1.72 and later and 1.68.1 and earlier).\n #\n # Define NO_PERL_MAKEMAKER if you cannot use Makefiles generated by perl's\n # MakeMaker (e.g. using ActiveState under Cygwin).\n-- \n1.6.5.rc1.199.g596ec\n"},{"id":"124446","messageId":"20091009101615.GB16558@progeny.tock","threadId":"21167","inReplyTo":"20091009101400.GA16549@progeny.tock","subject":"[PATCH 2/9] Documentation: git fmt-merge-message is not a script","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2009-10-09T10:16:15Z","receivedAt":"2009-10-09T10:16:15Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"The fmt-merge-message builtin is usually invoked as\n\"git fmt-merge-message\" rather than through the hard link in\nGIT_EXEC_PATH. Although this is unlikely to confuse most script\nwriters, it should not hurt to make the documentation a little\nclearer anyway.\n\nSigned-off-by: Jonathan Nieder \n---\n Documentation/git-fmt-merge-msg.txt | 2 +-\n Documentation/git-merge.txt | 7 ++++---\n 2 files changed, 5 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt\nindex 1c24796..0067805 100644\n--- a/Documentation/git-fmt-merge-msg.txt\n+++ b/Documentation/git-fmt-merge-msg.txt\n@@ -18,7 +18,7 @@ Takes the list of merged objects on stdin and produces a suitable\n commit message to be used for the merge commit, usually to be\n passed as the '' argument of 'git-merge'.\n \n-This script is intended mostly for internal use by scripts\n+This command is intended mostly for internal use by scripts\n automatically invoking 'git-merge'.\n \n OPTIONS\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex af68d69..354e9d9 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -28,9 +28,10 @@ OPTIONS\n include::merge-options.txt[]\n \n -m ::\n-\tThe commit message to be used for the merge commit (in case\n-\tit is created). The 'git-fmt-merge-msg' script can be used\n-\tto give a good default for automated 'git-merge' invocations.\n+\tSet the commit message to be used for the merge commit (in\n+\tcase one is created). The 'fmt-merge-msg' Git command can be\n+\tused to give a good default for automated 'git-merge'\n+\tinvocations.\n \n ...::\n \tOther branch heads to merge into our branch. You need at\n-- \n1.6.5.rc1.199.g596ec\n"},{"id":"124447","messageId":"20091009101657.GC16558@progeny.tock","threadId":"21167","inReplyTo":"20091009101400.GA16549@progeny.tock","subject":"[PATCH 3/9] Documentation: fix singular/plural mismatch","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2009-10-09T10:16:57Z","receivedAt":"2009-10-09T10:16:57Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Sounds better this way, at least to my ears. (\"syntax and\nsupported options of git merge\" is a plural noun.)\n\nSigned-off-by: Jonathan Nieder \n---\n Documentation/config.txt | 2 +-\n Documentation/git-merge.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex be0b8ca..4d01dde 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -539,7 +539,7 @@ branch..merge::\n \n branch..mergeoptions::\n \tSets default options for merging into branch . The syntax and\n-\tsupported options are equal to that of linkgit:git-merge[1], but\n+\tsupported options are equal to those of linkgit:git-merge[1], but\n \toption values containing whitespace characters are currently not\n \tsupported.\n \ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex 354e9d9..6da07bb 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -50,7 +50,7 @@ include::merge-config.txt[]\n \n branch..mergeoptions::\n \tSets default options for merging into branch . The syntax and\n-\tsupported options are equal to that of 'git-merge', but option values\n+\tsupported options are equal to those of 'git-merge', but option values\n \tcontaining whitespace characters are currently not supported.\n \n HOW MERGE WORKS\n-- \n1.6.5.rc1.199.g596ec\n"},{"id":"124445","messageId":"20091009101743.GD16558@progeny.tock","threadId":"21167","inReplyTo":"20091009101400.GA16549@progeny.tock","subject":"[PATCH 4/9] Documentation: say \"the same\" instead of \"equal\"","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2009-10-09T10:17:43Z","receivedAt":"2009-10-09T10:17:43Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"When non-mathematical objects are declared equal in documentation,\nthis is a sign that perhaps the discussion is becoming too\ntechnical or exact. Use \"same\" instead if no other nuance is\nrequired.\n\nSigned-off-by: Jonathan Nieder \n---\n Documentation/config.txt | 2 +-\n Documentation/git-merge.txt | 4 ++--\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex 4d01dde..cd17814 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -539,7 +539,7 @@ branch..merge::\n \n branch..mergeoptions::\n \tSets default options for merging into branch . The syntax and\n-\tsupported options are equal to those of linkgit:git-merge[1], but\n+\tsupported options are the same as those of linkgit:git-merge[1], but\n \toption values containing whitespace characters are currently not\n \tsupported.\n \ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex 6da07bb..6ffd4b0 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -50,8 +50,8 @@ include::merge-config.txt[]\n \n branch..mergeoptions::\n \tSets default options for merging into branch . The syntax and\n-\tsupported options are equal to those of 'git-merge', but option values\n-\tcontaining whitespace characters are currently not supported.\n+\tsupported options are the same as those of 'git-merge', but option\n+\tvalues containing whitespace characters are currently not supported.\n \n HOW MERGE WORKS\n ---------------\n-- \n1.6.5.rc1.199.g596ec\n"},{"id":"124453","messageId":"20091009101825.GE16558@progeny.tock","threadId":"21167","inReplyTo":"20091009101400.GA16549@progeny.tock","subject":"[PATCH 5/9] Documentation: clone: clarify discussion of initial branch","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2009-10-09T10:18:25Z","receivedAt":"2009-10-09T10:18:25Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"When saying the initial branch is equal to the currently active\nremote branch, it is probably intended that the branch heads\npoint to the same commit. Maybe it would be more useful to a new\nuser to emphasize that the tree contents and history are the\nsame.\n\nMore important, probably, is that this new branch is set up so\nthat \"git pull\" merges changes from the corresponding remote\nbranch. The next paragraph addresses that directly, but\nclarifying the initial content of the branch should make it\nclearer why a pull is required at all (that local and remote\nbranches each have their own history after the clone).\n\nSigned-off-by: Jonathan Nieder \n---\n Documentation/git-clone.txt | 3 ++-\n 1 files changed, 2 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex aacf4fd..7cd06e2 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -20,7 +20,8 @@ DESCRIPTION\n Clones a repository into a newly created directory, creates\n remote-tracking branches for each branch in the cloned repository\n (visible using `git branch -r`), and creates and checks out an initial\n-branch equal to the cloned repository's currently active branch.\n+branch with the contents of the cloned repository's currently active\n+branch.\n \n After the clone, a plain `git fetch` without arguments will update\n all the remote-tracking branches, and a `git pull` without\n-- \n1.6.5.rc1.199.g596ec\n"},{"id":"124448","messageId":"20091009101858.GF16558@progeny.tock","threadId":"21167","inReplyTo":"20091009101400.GA16549@progeny.tock","subject":"[PATCH 6/9] Documentation: branch: update --merged description","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2009-10-09T10:18:58Z","receivedAt":"2009-10-09T10:18:58Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Update the documentation for --merged and --no-merged to explain\nthe meaning of the optional parameter introduced in commit 049716b\n(branch --merged/--no-merged: allow specifying arbitrary commit,\n2008-07-08).\n\nSigned-off-by: Jonathan Nieder \n---\n Documentation/git-branch.txt | 10 ++++++----\n 1 files changed, 6 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex aad71dc..e8b32a2 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -134,11 +134,13 @@ start-point is either a local or remote branch.\n --contains ::\n \tOnly list branches which contain the specified commit.\n \n---merged::\n-\tOnly list branches which are fully contained by HEAD.\n+--merged []::\n+\tOnly list branches whose tips are reachable from the\n+\tspecified commit (HEAD if not specified).\n \n---no-merged::\n-\tDo not list branches which are fully contained by HEAD.\n+--no-merged []::\n+\tDo not list branches whose tips are reachable from the\n+\tspecified commit (HEAD if not specified).\n \n ::\n \tThe name of the branch to create or delete.\n-- \n1.6.5.rc1.199.g596ec\n"},{"id":"124449","messageId":"20091009101940.GG16558@progeny.tock","threadId":"21167","inReplyTo":"20091009101400.GA16549@progeny.tock","subject":"[PATCH 7/9] Documentation: clarify branch creation","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2009-10-09T10:19:40Z","receivedAt":"2009-10-09T10:19:40Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"The documentation seems to assume that the starting point for a new\nbranch is the tip of an existing (ordinary) branch, but that is not\nthe most common case. More often, \"git branch\" is used to begin\na branch from a remote-tracking branch, a tag, or an interesting\ncommit (e.g. origin/pu^2). Clarify the language so it can apply\nto these cases.\n\nSigned-off-by: Jonathan Nieder \n---\n Documentation/git-branch.txt | 17 ++++++++++-------\n 1 files changed, 10 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex e8b32a2..990f782 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -30,10 +30,11 @@ commit) will be listed. With `--no-merged` only branches not merged into\n the named commit will be listed. If the argument is missing it\n defaults to 'HEAD' (i.e. the tip of the current branch).\n \n-In the command's second form, a new branch named will be created.\n-It will start out with a head equal to the one given as .\n-If no is given, the branch will be created with a head\n-equal to that of the currently checked out branch.\n+In the command's second form, creates a new branch named .\n+The branch will start out with head pointing to the commit\n+. If no is given, the branch will start\n+out with head pointing to the tip of the currently checked out branch,\n+or the currently checked out commit if no branch is checked out.\n \n Note that this will create the new branch, but it will not switch the\n working tree to it; use \"git checkout \" to switch to the\n@@ -149,9 +150,11 @@ start-point is either a local or remote branch.\n \tmay restrict the characters allowed in a branch name.\n \n ::\n-\tThe new branch will be created with a HEAD equal to this. It may\n-\tbe given as a branch name, a commit-id, or a tag. If this option\n-\tis omitted, the current branch is assumed.\n+\tThe new branch head will point to this commit. It may be\n+\tgiven as a branch name, a commit-id, or a tag. If this\n+\toption is omitted, the currently checked out branch head\n+\tis used, or the current commit if no branch is checked\n+\tout.\n \n ::\n \tThe name of an existing branch to rename.\n-- \n1.6.5.rc1.199.g596ec\n"},{"id":"124450","messageId":"20091009102019.GH16558@progeny.tock","threadId":"21167","inReplyTo":"20091009101400.GA16549@progeny.tock","subject":"[PATCH 8/9] Documentation: clarify \"working tree\" definition","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2009-10-09T10:20:19Z","receivedAt":"2009-10-09T10:20:19Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"It is not necessarily obvious to a git novice what it means for a\nfilesystem tree to be equal to the HEAD. Spell it out.\n\nSigned-off-by: Jonathan Nieder \n---\n Documentation/glossary-content.txt | 6 +++---\n 1 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex 572374f..43d84d1 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -456,6 +456,6 @@ This commit is referred to as a \"merge commit\", or sometimes just a\n \tof 'A' is 'origin/B' sometimes we say \"'A' is tracking 'origin/B'\".\n \n [[def_working_tree]]working tree::\n-\tThe tree of actual checked out files. The working tree is\n-\tnormally equal to the <> plus any local changes\n-\tthat you have made but not yet committed.\n+\tThe tree of actual checked out files. The working tree normally\n+\tcontains the contents of the <> commit's tree,\n+\tplus any local changes that you have made but not yet committed.\n-- \n1.6.5.rc1.199.g596ec\n"},{"id":"124452","messageId":"20091009102554.GI16558@progeny.tock","threadId":"21167","inReplyTo":"20091009101400.GA16549@progeny.tock","subject":"[PATCH 9/9] racy-git.txt: explain nsec problem in more detail","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2009-10-09T10:25:54Z","receivedAt":"2009-10-09T10:25:54Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Idealists may want USE_NSEC to be the default on Linux some day.\nPoint to a patch to better explain the requirements on\nfilesystem code for that to happen.\n\nSigned-off-by: Jonathan Nieder \n---\nAm I understanding the problem here correctly? It seems to me\nthat ext2/3/4, tmpfs, ntfs, and so on shouldn’t have problems\nwith USE_NSEC, and all that is left is the monster that is\nnetworked filesystems.\n\n Documentation/technical/racy-git.txt | 10 ++++++----\n 1 files changed, 6 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.txt\nindex 48bb97f..53aa0c8 100644\n--- a/Documentation/technical/racy-git.txt\n+++ b/Documentation/technical/racy-git.txt\n@@ -42,10 +42,12 @@ compared, but this is not enabled by default because this member\n is not stable on network filesystems. With `USE_NSEC`\n compile-time option, `st_mtim.tv_nsec` and `st_ctim.tv_nsec`\n members are also compared, but this is not enabled by default\n-because the value of this member becomes meaningless once the\n-inode is evicted from the inode cache on filesystems that do not\n-store it on disk.\n-\n+because in-core timestamps can have finer granularity than\n+on-disk timestamps, resulting in meaningless changes when an\n+inode is evicted from the inode cache. See commit 8ce13b0\n+of git://git.kernel.org/pub/scm/linux/kernel/git/tglx/history.git\n+([PATCH] Sync in core time granuality with filesystems,\n+2005-01-04).\n \n Racy git\n --------\n-- \n1.6.5.rc1.199.g596ec\n"},{"id":"124511","messageId":"BLU0-SMTP425A9541141B09D790814EAECB0@phx.gbl","threadId":"21167","inReplyTo":"20091009101940.GG16558@progeny.tock","subject":"Re: [PATCH 7/9] Documentation: clarify branch creation","fromName":"Sean Estabrooks","fromEmail":"seanlkml@sympatico.ca","sentAt":"2009-10-09T16:21:51Z","receivedAt":"2009-10-09T16:21:51Z","isPatch":true,"sender":{"key":"seanlkml@sympatico.ca","avatar":"https://gravatar.com/avatar/f92923f54fc08c401fc59b71829d4b89e9b8087fbba45ff87c82e6a83aee02ae?d=mp&s=160"},"body":"On Fri, 9 Oct 2009 05:19:40 -0500\nJonathan Nieder wrote:\n\n> +In the command's second form, creates a new branch named .\n> +The branch will start out with head pointing to the commit\n> +. If no is given, the branch will start\n> +out with head pointing to the tip of the currently checked out branch,\n> +or the currently checked out commit if no branch is checked out.\n\nThe first sentence here doesn't quite work, perhaps drop the \"In\". But\nthe whole thing is a bit verbose, what about just:\n\nThe command's second form creates a new branch named which\npoints to the current HEAD or if given.\n\n> ::\n> -\tThe new branch will be created with a HEAD equal to this. It may\n> -\tbe given as a branch name, a commit-id, or a tag. If this option\n> -\tis omitted, the current branch is assumed.\n> +\tThe new branch head will point to this commit. It may be\n> +\tgiven as a branch name, a commit-id, or a tag. If this\n> +\toption is omitted, the currently checked out branch head\n> +\tis used, or the current commit if no branch is checked\n> +\tout.\n\nMaybe it's not worth worrying about, but couldn't the last sentence\nbe just:\n\n If this option is omitted, the current HEAD will be used instead.\n\nSean\n\nP.S. Patches 3 and 4 in this series would be better as a single patch.\n"},{"id":"124516","messageId":"20091009183408.GB2477@progeny.tock","threadId":"21167","inReplyTo":"BLU0-SMTP425A9541141B09D790814EAECB0@phx.gbl","subject":"Re: [PATCH 7/9] Documentation: clarify branch creation","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2009-10-09T18:34:08Z","receivedAt":"2009-10-09T18:34:08Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Sean Estabrooks wrote:\n> On Fri, 9 Oct 2009 05:19:40 -0500\n> Jonathan Nieder wrote:\n> \n> > +In the command's second form, creates a new branch named .\n> > +The branch will start out with head pointing to the commit\n> > +. If no is given, the branch will start\n> > +out with head pointing to the tip of the currently checked out branch,\n> > +or the currently checked out commit if no branch is checked out.\n> \n> The first sentence here doesn't quite work, perhaps drop the \"In\". But\n> the whole thing is a bit verbose, what about just:\n> \n> The command's second form creates a new branch named which\n> points to the current HEAD or if given.\n\nMakes sense. I modified this slightly to “new branch head” since the\nbranch itself does not point to anything.\n\n> > ::\n> > -\tThe new branch will be created with a HEAD equal to this. It may\n> > -\tbe given as a branch name, a commit-id, or a tag. If this option\n> > -\tis omitted, the current branch is assumed.\n> > +\tThe new branch head will point to this commit. It may be\n> > +\tgiven as a branch name, a commit-id, or a tag. If this\n> > +\toption is omitted, the currently checked out branch head\n> > +\tis used, or the current commit if no branch is checked\n> > +\tout.\n> \n> Maybe it's not worth worrying about, but couldn't the last sentence\n> be just:\n> \n> If this option is omitted, the current HEAD will be used instead.\n\nThat sounds better, thanks. The reader that does not know what HEAD is\nprobably needs to read the relevant section of the user manual for other\nreasons anyway.\n\nSo this page should probably point to the what-is-a-branch section of\nthe User's Manual. Maybe something like this?\n\n-- %< --\nSubject: Documentation: clarify branch creation\n\nThe documentation seems to assume that the starting point for a new\nbranch is the tip of an existing (ordinary) branch, but that is not\nthe most common case. More often, \"git branch\" is used to begin\na branch from a remote-tracking branch, a tag, or an interesting\ncommit (e.g. origin/pu^2). Clarify the language so it can apply\nto these cases. Thanks to Sean Estabrooks for the wording.\n\nAlso add a pointer to the user's manual for the bewildered.\n\nSigned-off-by: Jonathan Nieder \n---\n Documentation/git-branch.txt | 16 ++++++++--------\n 1 files changed, 8 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex e8b32a2..f766b4d 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -30,10 +30,8 @@ commit) will be listed. With `--no-merged` only branches not merged into\n the named commit will be listed. If the argument is missing it\n defaults to 'HEAD' (i.e. the tip of the current branch).\n \n-In the command's second form, a new branch named will be created.\n-It will start out with a head equal to the one given as .\n-If no is given, the branch will be created with a head\n-equal to that of the currently checked out branch.\n+The command's second form creates a new branch head named \n+which points to the current 'HEAD', or if given.\n \n Note that this will create the new branch, but it will not switch the\n working tree to it; use \"git checkout \" to switch to the\n@@ -149,9 +147,9 @@ start-point is either a local or remote branch.\n \tmay restrict the characters allowed in a branch name.\n \n ::\n-\tThe new branch will be created with a HEAD equal to this. It may\n-\tbe given as a branch name, a commit-id, or a tag. If this option\n-\tis omitted, the current branch is assumed.\n+\tThe new branch head will point to this commit. It may be\n+\tgiven as a branch name, a commit-id, or a tag. If this\n+\toption is omitted, the current HEAD will be used instead.\n \n ::\n \tThe name of an existing branch to rename.\n@@ -216,7 +214,9 @@ SEE ALSO\n --------\n linkgit:git-check-ref-format[1],\n linkgit:git-fetch[1],\n-linkgit:git-remote[1].\n+linkgit:git-remote[1],\n+link:user-manual.html#what-is-a-branch[``Understanding history: What is\n+a branch?''] in the Git User's Manual.\n \n Author\n ------\n-- \n1.6.5.rc1.199.g596ec\n"},{"id":"124519","messageId":"20091009185114.GA3610@progeny.tock","threadId":"21167","inReplyTo":"20091009101743.GD16558@progeny.tock","subject":"[PATCH 3-4/9 v2] Documentation: clarify mergeoptions description","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2009-10-09T18:51:14Z","receivedAt":"2009-10-09T18:51:14Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Sounds better this way, at least to my ears. (\"The syntax and\nsupported options of git merge\" is a plural noun. \"the same\"\ninstead of \"equal\" sounds less technical and seems to convey\nthe meaning better here.)\n\nSigned-off-by: Jonathan Nieder \n---\nSean Estabrooks wrote:\n\n> P.S. Patches 3 and 4 in this series would be better as a single patch.\n\nGood idea. Here's a squashed version.\n\n Documentation/config.txt | 2 +-\n Documentation/git-merge.txt | 4 ++--\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex be0b8ca..cd17814 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -539,7 +539,7 @@ branch..merge::\n \n branch..mergeoptions::\n \tSets default options for merging into branch . The syntax and\n-\tsupported options are equal to that of linkgit:git-merge[1], but\n+\tsupported options are the same as those of linkgit:git-merge[1], but\n \toption values containing whitespace characters are currently not\n \tsupported.\n \ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex 354e9d9..6ffd4b0 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -50,8 +50,8 @@ include::merge-config.txt[]\n \n branch..mergeoptions::\n \tSets default options for merging into branch . The syntax and\n-\tsupported options are equal to that of 'git-merge', but option values\n-\tcontaining whitespace characters are currently not supported.\n+\tsupported options are the same as those of 'git-merge', but option\n+\tvalues containing whitespace characters are currently not supported.\n \n HOW MERGE WORKS\n ---------------\n-- \n1.6.5.rc1.199.g596ec\n"},{"id":"124534","messageId":"7vskdsqlvh.fsf@alter.siamese.dyndns.org","threadId":"21167","inReplyTo":"20091009101825.GE16558@progeny.tock","subject":"Re: [PATCH 5/9] Documentation: clone: clarify discussion of initial branch","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-10-09T21:48:50Z","receivedAt":"2009-10-09T21:48:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> When saying the initial branch is equal to the currently active\n> remote branch, it is probably intended that the branch heads\n> point to the same commit. Maybe it would be more useful to a new\n> user to emphasize that the tree contents and history are the\n> same.\n>\n> More important, probably, is that this new branch is set up so\n> that \"git pull\" merges changes from the corresponding remote\n> branch.\n\nAll true, and \"with the contents of\" is dropping the \"history\" part.\nPerhaps\n\n ... creates and checks out an initial branch that is forked from the\n cloned repository's currently active branch.\n\nwould convey that (1) the initial branch is your own; if you do not pull,\nyou won't get updated, and that (2) the initial branch starts out at the\nsame commit as the upstream.\n\n> clarifying the initial content of the branch should make it\n> clearer why a pull is required at all (that local and remote\n> branches each have their own history after the clone).\n>\n> Signed-off-by: Jonathan Nieder \n> ---\n> Documentation/git-clone.txt | 3 ++-\n> 1 files changed, 2 insertions(+), 1 deletions(-)\n>\n> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\n> index aacf4fd..7cd06e2 100644\n> --- a/Documentation/git-clone.txt\n> +++ b/Documentation/git-clone.txt\n> @@ -20,7 +20,8 @@ DESCRIPTION\n> Clones a repository into a newly created directory, creates\n> remote-tracking branches for each branch in the cloned repository\n> (visible using `git branch -r`), and creates and checks out an initial\n> -branch equal to the cloned repository's currently active branch.\n> +branch with the contents of the cloned repository's currently active\n> +branch.\n> \n> After the clone, a plain `git fetch` without arguments will update\n> all the remote-tracking branches, and a `git pull` without\n> -- \n> 1.6.5.rc1.199.g596ec\n>\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at http://vger.kernel.org/majordomo-info.html\n"},{"id":"124542","messageId":"20091009230739.GC4605@progeny.tock","threadId":"21167","inReplyTo":"7vskdsqlvh.fsf@alter.siamese.dyndns.org","subject":"[PATCH 5/9 v2] Documentation: clone: clarify discussion of initial branch","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2009-10-09T23:07:39Z","receivedAt":"2009-10-09T23:07:39Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"When saying the initial branch is equal to the currently active\nremote branch, it is probably intended that the branch heads\npoint to the same commit. Maybe it would be more useful to a\nnew user to emphasize that the tree contents and history are the\nsame.\n\nMore important, probably, is that this new branch is set up so\nthat \"git pull\" merges changes from the corresponding remote\nbranch. The next paragraph addresses that directly. What the\nreader needs to know to begin with is that (1) the initial branch\nis your own; if you do not pull, it won't get updated, and that\n(2) the initial branch starts out at the same commit as the\nupstream.\n\nThanks to Junio C Hamano for the wording.\n\nSigned-off-by: Jonathan Nieder \n---\nJunio C Hamano wrote:\n\n> Perhaps\n> \n> ... creates and checks out an initial branch that is forked from the\n> cloned repository's currently active branch.\n> \n> would convey that (1) the initial branch is your own; if you do not pull,\n> you won't get updated, and that (2) the initial branch starts out at the\n> same commit as the upstream.\n\nThat does work better. Explanation stolen for the commit message ---\nI hope you don't mind.\n\nThanks,\nJonathan\n\n Documentation/git-clone.txt | 5 +++--\n 1 files changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex aacf4fd..5ebcba1 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -19,8 +19,9 @@ DESCRIPTION\n \n Clones a repository into a newly created directory, creates\n remote-tracking branches for each branch in the cloned repository\n-(visible using `git branch -r`), and creates and checks out an initial\n-branch equal to the cloned repository's currently active branch.\n+(visible using `git branch -r`), and creates and checks out an\n+initial branch that is forked from the cloned repository's\n+currently active branch.\n \n After the clone, a plain `git fetch` without arguments will update\n all the remote-tracking branches, and a `git pull` without\n-- \n1.6.5.rc1.199.g596ec\n"},{"id":"124543","messageId":"7vskdsf4mn.fsf@alter.siamese.dyndns.org","threadId":"21167","inReplyTo":"20091009101858.GF16558@progeny.tock","subject":"Re: [PATCH 6/9] Documentation: branch: update --merged description","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-10-10T00:56:48Z","receivedAt":"2009-10-10T00:56:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> Update the documentation for --merged and --no-merged to explain\n> the meaning of the optional parameter introduced in commit 049716b\n> (branch --merged/--no-merged: allow specifying arbitrary commit,\n> 2008-07-08).\n>\n> Signed-off-by: Jonathan Nieder \n\nThanks.\n\nI most often use --no-merged this way:\n\n\t$ git branch --no-merged pu\n\nto see topics that are queued but not merged anywhere. This is not about\n\"do not list\", but \"do show the ones that are not merged\", so I reworded\nthe description of the latter in your patch.\n\n> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\n> index aad71dc..e8b32a2 100644\n> --- a/Documentation/git-branch.txt\n> +++ b/Documentation/git-branch.txt\n> @@ -134,11 +134,13 @@ start-point is either a local or remote branch.\n> --contains ::\n> \tOnly list branches which contain the specified commit.\n> \n> ---merged::\n> -\tOnly list branches which are fully contained by HEAD.\n> +--merged []::\n> +\tOnly list branches whose tips are reachable from the\n> +\tspecified commit (HEAD if not specified).\n> \n> ---no-merged::\n> -\tDo not list branches which are fully contained by HEAD.\n> +--no-merged []::\n> +\tOnly list branches whose tips are not reachable from the\n> +\tspecified commit (HEAD if not specified).\n> \n> ::\n> \tThe name of the branch to create or delete.\n> -- \n> 1.6.5.rc1.199.g596ec\n>\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at http://vger.kernel.org/majordomo-info.html\n"},{"id":"124544","messageId":"7vmy40f4mi.fsf@alter.siamese.dyndns.org","threadId":"21167","inReplyTo":"20091009102554.GI16558@progeny.tock","subject":"Re: [PATCH 9/9] racy-git.txt: explain nsec problem in more detail","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-10-10T00:56:53Z","receivedAt":"2009-10-10T00:56:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> Am I understanding the problem here correctly?\n\nI think so ;-).\n"},{"id":"124551","messageId":"7viqeodq0s.fsf@alter.siamese.dyndns.org","threadId":"21167","inReplyTo":"20091009183408.GB2477@progeny.tock","subject":"Re: [PATCH 7/9] Documentation: clarify branch creation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-10-10T00:57:39Z","receivedAt":"2009-10-10T00:57:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> So this page should probably point to the what-is-a-branch section of\n> the User's Manual. Maybe something like this?\n\nSounds good. Thanks\n\n> -- %< --\n> Subject: Documentation: clarify branch creation\n>\n> The documentation seems to assume that the starting point for a new\n> branch is the tip of an existing (ordinary) branch, but that is not\n> the most common case. More often, \"git branch\" is used to begin\n> a branch from a remote-tracking branch, a tag, or an interesting\n> commit (e.g. origin/pu^2). Clarify the language so it can apply\n> to these cases. Thanks to Sean Estabrooks for the wording.\n>\n> Also add a pointer to the user's manual for the bewildered.\n> ...\n"},{"id":"124553","messageId":"7vzl80cbey.fsf@alter.siamese.dyndns.org","threadId":"21167","inReplyTo":"20091009101400.GA16549@progeny.tock","subject":"Re: [PATCH 0/9] Documentation tweaks","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-10-10T00:58:29Z","receivedAt":"2009-10-10T00:58:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> Here are some small documentation patches that have been sitting in\n> my tree for a while. Most important is the first one, which makes it\n> easier to find the appropriate options for building documentation\n> from source on a new machine.\n\nThanks.\n"}]}