{"thread":{"id":"36752","subject":"[PATCH v2] wording fixes in the user manual and glossary","startedAt":"2014-05-26T14:20:23Z","lastAt":"2014-05-27T19:52:00Z","messageCount":2,"participants":["Jeremiah Mahler","Junio C Hamano"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"242668","messageId":"1401114023-4015-1-git-send-email-jmmahler@gmail.com","threadId":"36752","inReplyTo":null,"subject":"[PATCH v2] wording fixes in the user manual and glossary","fromName":"Jeremiah Mahler","fromEmail":"jmmahler@gmail.com","sentAt":"2014-05-26T14:20:23Z","receivedAt":"2014-05-26T14:20:23Z","isPatch":true,"sender":{"key":"jmmahler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/154028?v=4"},"body":"Various minor wording fixes throughout the user manual\nand glossary.\n\nThe section on \"Updating a repository with git fetch\" was\nsubstantially re-worded to try and better explain `git fetch`.\n\nSigned-off-by: Jeremiah Mahler <jmmahler@gmail.com>\n---\n\nNotes:\n    From the feedback I received by Chris Packham [1] it was clear\n    that my re-wording of the section \"Updating a repository with git fetch\"\n    still wasn't quite right [1].\n    \n    [1]: http://marc.info/?l=git&m=140100460903936&w=2\n    \n    I re-worded it some more to try and emphasize the remote (upstream)\n    and local aspects of `git fetch`.  Chris liked those changes better [2].\n    \n    [2]: http://marc.info/?l=git&m=140109062903038&w=2\n    \n    I expanded upon this even further.  The section on git-pull is similar\n    so I tried to use that as a basis.  I also thought the relationship between\n    git fetch and git pull was worthy of a short note along with a link to\n    the section on git-pull.\n\n Documentation/glossary-content.txt |  2 +-\n Documentation/user-manual.txt      | 28 ++++++++++++++++++----------\n 2 files changed, 19 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex be0858c..4e0b971 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -1,7 +1,7 @@\n [[def_alternate_object_database]]alternate object database::\n \tVia the alternates mechanism, a <<def_repository,repository>>\n \tcan inherit part of its <<def_object_database,object database>>\n-\tfrom another object database, which is called \"alternate\".\n+\tfrom another object database, which is called an \"alternate\".\n \n [[def_bare_repository]]bare repository::\n \tA bare repository is normally an appropriately\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex d33f884..f5fd61b 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -416,14 +416,22 @@ REVISIONS\" section of linkgit:gitrevisions[7].\n Updating a repository with git fetch\n ------------------------------------\n \n-Eventually the developer cloned from will do additional work in her\n-repository, creating new commits and advancing the branches to point\n-at the new commits.\n+After you clone a repository and commit a few changes of your own, you\n+may wish to check the original repository for updates.\n+The linkgit:git-fetch[1] command is used to update all the remote-tracking\n+branches to the latest version found in those repositories.\n+It will not touch any of your own branches--not even the \"master\"\n+branch that was created during clone.\n+The linkgit:git-merge[1] command can then be used to merge the changes.\n+\n+-------------------------------------------------\n+$ git fetch\n+$ git merge origin/master\n+-------------------------------------------------\n \n-The command `git fetch`, with no arguments, will update all of the\n-remote-tracking branches to the latest version found in her\n-repository.  It will not touch any of your own branches--not even the\n-\"master\" branch that was created for you on clone.\n+The linkgit:git-pull[1] command,\n+<<getting-updates-With-git-pull,discussed later>>,\n+performs both of these steps, a fetch followed by a merge.\n \n [[fetching-branches]]\n Fetching branches from other repositories\n@@ -1811,8 +1819,8 @@ manner.\n You can then import these into your mail client and send them by\n hand.  However, if you have a lot to send at once, you may prefer to\n use the linkgit:git-send-email[1] script to automate the process.\n-Consult the mailing list for your project first to determine how they\n-prefer such patches be handled.\n+Consult the mailing list for your project first to determine\n+their requirements for submitting patches.\n \n [[importing-patches]]\n Importing patches to a project\n@@ -2255,7 +2263,7 @@ $ git checkout test && git merge speed-up-spinlocks\n It is unlikely that you would have any conflicts here ... but you might if you\n spent a while on this step and had also pulled new versions from upstream.\n \n-Some time later when enough time has passed and testing done, you can pull the\n+Sometime later when enough time has passed and testing done, you can pull the\n same branch into the `release` tree ready to go upstream.  This is where you\n see the value of keeping each patch (or patch series) in its own branch.  It\n means that the patches can be moved into the `release` tree in any order.\n-- \n2.0.0.rc4.480.gad29d77\n"},{"id":"242772","messageId":"xmqq4n0bf19b.fsf@gitster.dls.corp.google.com","threadId":"36752","inReplyTo":"1401114023-4015-1-git-send-email-jmmahler@gmail.com","subject":"Re: [PATCH v2] wording fixes in the user manual and glossary","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-05-27T19:52:00Z","receivedAt":"2014-05-27T19:52:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeremiah Mahler <jmmahler@gmail.com> writes:\n\n> Various minor wording fixes throughout the user manual\n> and glossary.\n>\n> The section on \"Updating a repository with git fetch\" was\n> substantially re-worded to try and better explain `git fetch`.\n>\n> Signed-off-by: Jeremiah Mahler <jmmahler@gmail.com>\n> ---\n>\n> Notes:\n>     From the feedback I received by Chris Packham [1] it was clear\n>     that my re-wording of the section \"Updating a repository with git fetch\"\n>     still wasn't quite right [1].\n>     \n>     [1]: http://marc.info/?l=git&m=140100460903936&w=2\n>     \n>     I re-worded it some more to try and emphasize the remote (upstream)\n>     and local aspects of `git fetch`.  Chris liked those changes better [2].\n>     \n>     [2]: http://marc.info/?l=git&m=140109062903038&w=2\n>     \n>     I expanded upon this even further.  The section on git-pull is similar\n>     so I tried to use that as a basis.  I also thought the relationship between\n>     git fetch and git pull was worthy of a short note along with a link to\n>     the section on git-pull.\n>\n>  Documentation/glossary-content.txt |  2 +-\n>  Documentation/user-manual.txt      | 28 ++++++++++++++++++----------\n>  2 files changed, 19 insertions(+), 11 deletions(-)\n>\n> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n> index be0858c..4e0b971 100644\n> --- a/Documentation/glossary-content.txt\n> +++ b/Documentation/glossary-content.txt\n> @@ -1,7 +1,7 @@\n>  [[def_alternate_object_database]]alternate object database::\n>  \tVia the alternates mechanism, a <<def_repository,repository>>\n>  \tcan inherit part of its <<def_object_database,object database>>\n> -\tfrom another object database, which is called \"alternate\".\n> +\tfrom another object database, which is called an \"alternate\".\n>  \n>  [[def_bare_repository]]bare repository::\n>  \tA bare repository is normally an appropriately\n> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\n> index d33f884..f5fd61b 100644\n> --- a/Documentation/user-manual.txt\n> +++ b/Documentation/user-manual.txt\n> @@ -416,14 +416,22 @@ REVISIONS\" section of linkgit:gitrevisions[7].\n>  Updating a repository with git fetch\n>  ------------------------------------\n>  \n> -Eventually the developer cloned from will do additional work in her\n> -repository, creating new commits and advancing the branches to point\n> -at the new commits.\n> +After you clone a repository and commit a few changes of your own, you\n> +may wish to check the original repository for updates.\n\nThe above is very good.\n\n> +The linkgit:git-fetch[1] command is used to update all the remote-tracking\n> +branches to the latest version found in those repositories.\n> +It will not touch any of your own branches--not even the \"master\"\n> +branch that was created during clone.\n\nIt is harder to review with unnecessary rewrapping of the text X-<.\n\nI somehow feel that the original was clear around here, by being\nexplicit that \"git fetch $there $that\" is not it is talking about,\nwhich seems to have been lost in this update.\n\n\n> +The linkgit:git-merge[1] command can then be used to merge the changes.\n> +\n> +-------------------------------------------------\n> +$ git fetch\n> +$ git merge origin/master\n> +-------------------------------------------------\n\nThat is not wrong per-se, but it is not a very good example.  If you\nimmediately merge, there is no reason not to say \"git pull\" in the\nfirst place ;-)  For this to be a good example, there needs\n\n\tgit log -p ..origin/master\n\nbefore that merge happens, I would think.\n\nNot that I read the text around here and confirmed that this is a\ngood place in the overall flow of the learning to teach about \"log\n-p\" and \"merge\", though.\n\n> @@ -1811,8 +1819,8 @@ manner.\n>  You can then import these into your mail client and send them by\n>  hand.  However, if you have a lot to send at once, you may prefer to\n>  use the linkgit:git-send-email[1] script to automate the process.\n> -Consult the mailing list for your project first to determine how they\n> -prefer such patches be handled.\n> +Consult the mailing list for your project first to determine\n> +their requirements for submitting patches.\n\nOK.\n\n>  [[importing-patches]]\n>  Importing patches to a project\n> @@ -2255,7 +2263,7 @@ $ git checkout test && git merge speed-up-spinlocks\n>  It is unlikely that you would have any conflicts here ... but you might if you\n>  spent a while on this step and had also pulled new versions from upstream.\n>  \n> -Some time later when enough time has passed and testing done, you can pull the\n> +Sometime later when enough time has passed and testing done, you can pull the\n\nOK.\n"}]}