{"thread":{"id":"36787","subject":"[PATCH 0/5] Documentation updates for 'git fetch'","startedAt":"2014-05-29T22:42:25Z","lastAt":"2014-06-02T18:24:31Z","messageCount":15,"participants":["Junio C Hamano","Marc Branchaud"],"isPatch":true,"patchVersion":1,"patchTotal":5},"messages":[{"id":"242983","messageId":"1401403350-7122-1-git-send-email-gitster@pobox.com","threadId":"36787","inReplyTo":null,"subject":"[PATCH 0/5] Documentation updates for 'git fetch'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-05-29T22:42:25Z","receivedAt":"2014-05-29T22:42:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Noticed that this page has antiquated description, which may still\nbe correct, that can use some modernization.\n\nThere are a few more larger updates coming, but these are small\nenough to be reviewed separately and quickly, so I am sending them\nout early.\n\nJunio C Hamano (5):\n fetch doc: update introductory part for clarity\n fetch doc: update note on '+' in front of the refspec\n fetch doc: remove notes on outdated \"mixed layout\"\n fetch doc: on pulling multiple refspecs\n fetch doc: update refspec format description\n\n Documentation/git-fetch.txt | 29 ++++++++++++++-----------\n Documentation/pull-fetch-param.txt | 44 ++++++++++++++++----------------------\n 2 files changed, 34 insertions(+), 39 deletions(-)\n\n-- \n2.0.0-479-g59ac8f9\n"},{"id":"242984","messageId":"1401403350-7122-2-git-send-email-gitster@pobox.com","threadId":"36787","inReplyTo":"1401403350-7122-1-git-send-email-gitster@pobox.com","subject":"[PATCH 1/5] fetch doc: update introductory part for clarity","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-05-29T22:42:26Z","receivedAt":"2014-05-29T22:42:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":" - \"Branches\" is a more common way to say \"heads\" in these days.\n\n - Remote-tracking branches are used a lot more these days and it is\n worth mentioning that it is one of the primary side effects of\n the command to update them.\n\n - Avoid \"X. That means Y.\" If Y is easier to understand to\n readers, just say that upfront.\n\n - Use of explicit refspec to fetch tags does not have much to do\n with turning \"auto following\" on or off. It is a way to fetch\n tags that otherwise would not be fetched by auto-following.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/git-fetch.txt | 29 ++++++++++++++++-------------\n 1 file changed, 16 insertions(+), 13 deletions(-)\n\ndiff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt\nindex 5809aa4..d5f5b54 100644\n--- a/Documentation/git-fetch.txt\n+++ b/Documentation/git-fetch.txt\n@@ -17,20 +17,23 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Fetches named heads or tags from one or more other repositories,\n-along with the objects necessary to complete them.\n-\n-The ref names and their object names of fetched refs are stored\n-in `.git/FETCH_HEAD`. This information is left for a later merge\n-operation done by 'git merge'.\n-\n-By default, tags are auto-followed. This means that when fetching\n-from a remote, any tags on the remote that point to objects that exist\n-in the local repository are fetched. The effect is to fetch tags that\n+Fetch branches and/or tags (collectively, \"refs\") from one or more\n+other repositories, along with the objects necessary to complete the\n+histories of them.\n+\n+The names of refs that are fetched, together with the object names\n+they point at, are written to `.git/FETCH_HEAD`. This information\n+is used by a later merge operation done by 'git merge'. In addition,\n+the remote-tracking branches may be updated (see description on\n+ below for details).\n+\n+By default, any tag that points into the histories being fetched is\n+also fetched; the effect is to fetch tags that\n point at branches that you are interested in. This default behavior\n-can be changed by using the --tags or --no-tags options, by\n-configuring remote..tagopt, or by using a refspec that fetches\n-tags explicitly.\n+can be changed by using the --tags or --no-tags options or by\n+configuring remote..tagopt. By using a refspec that fetches tags\n+explicitly, you can fetch tags that do not point into branches you\n+are interested in as well.\n \n 'git fetch' can fetch from either a single named repository,\n or from several repositories at once if is given and\n-- \n2.0.0-479-g59ac8f9\n"},{"id":"242985","messageId":"1401403350-7122-3-git-send-email-gitster@pobox.com","threadId":"36787","inReplyTo":"1401403350-7122-1-git-send-email-gitster@pobox.com","subject":"[PATCH 2/5] fetch doc: update note on '+' in front of the refspec","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-05-29T22:42:27Z","receivedAt":"2014-05-29T22:42:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"While it is not *wrong* per-se to say that pulling a rewound/rebased\nbranch will lead to an unnecessary merge conflict, that is not what\nthe leading \"+\" sign to allow non-fast-forward update of remote-tracking\nbranch is at all.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/pull-fetch-param.txt | 18 +++++++++---------\n 1 file changed, 9 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt\nindex 18cffc2..2a7e2b7 100644\n--- a/Documentation/pull-fetch-param.txt\n+++ b/Documentation/pull-fetch-param.txt\n@@ -24,15 +24,15 @@ is updated even if it does not result in a fast-forward\n update.\n +\n [NOTE]\n-If the remote branch from which you want to pull is\n-modified in non-linear ways such as being rewound and\n-rebased frequently, then a pull will attempt a merge with\n-an older version of itself, likely conflict, and fail.\n-It is under these conditions that you would want to use\n-the `+` sign to indicate non-fast-forward updates will\n-be needed. There is currently no easy way to determine\n-or declare that a branch will be made available in a\n-repository with this behavior; the pulling user simply\n+When the remote branch you want to fetch is known to\n+be rewound and rebased regularly, it is expected that\n+the tip of it will not be descendant of the commit that\n+used to be at its tip the last time you fetched it and\n+stored in your remote-tracking branch. You would want\n+to use the `+` sign to indicate non-fast-forward updates\n+will be needed for such branches. There is no way to\n+determine or declare that a branch will be made available\n+in a repository with this behavior; the pulling user simply\n must know this is the expected usage pattern for a branch.\n +\n [NOTE]\n-- \n2.0.0-479-g59ac8f9\n"},{"id":"242986","messageId":"1401403350-7122-4-git-send-email-gitster@pobox.com","threadId":"36787","inReplyTo":"1401403350-7122-1-git-send-email-gitster@pobox.com","subject":"[PATCH 3/5] fetch doc: remove notes on outdated \"mixed layout\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-05-29T22:42:28Z","receivedAt":"2014-05-29T22:42:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"In old days before Git 1.5, it was customery for \"git fetch\" to use\nthe same local branch namespace to keep track of the remote-tracking\nbranches, and it was necessary to tell users not to check them out\nand commit on them. Since everybody uses the separate remote layout\nthese days, there is no need to warn against the practice to check\nout the right-hand side of and build on it---the RHS is\ntypically not even a local branch.\n\nIncidentally, this also kills one mention of \"Pull:\" line of\n$GIT_DIR/remotes/* configuration, which is a lot less familiar to\nnew people than the more modern remote.*.fetch configuration\nvariable.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/pull-fetch-param.txt | 13 -------------\n 1 file changed, 13 deletions(-)\n\ndiff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt\nindex 2a7e2b7..e266c2d 100644\n--- a/Documentation/pull-fetch-param.txt\n+++ b/Documentation/pull-fetch-param.txt\n@@ -36,19 +36,6 @@ in a repository with this behavior; the pulling user simply\n must know this is the expected usage pattern for a branch.\n +\n [NOTE]\n-You never do your own development on branches that appear\n-on the right hand side of a colon on `Pull:` lines;\n-they are to be updated by 'git fetch'. If you intend to do\n-development derived from a remote branch `B`, have a `Pull:`\n-line to track it (i.e. `Pull: B:remote-B`), and have a separate\n-branch `my-B` to do your development on top of it. The latter\n-is created by `git branch my-B remote-B` (or its equivalent `git\n-checkout -b my-B remote-B`). Run `git fetch` to keep track of\n-the progress of the remote side, and when you see something new\n-on the remote branch, merge it into your development branch with\n-`git pull . remote-B`, while you are on `my-B` branch.\n-+\n-[NOTE]\n There is a difference between listing multiple \n directly on 'git pull' command line and having multiple\n `Pull:` lines for a and running\n-- \n2.0.0-479-g59ac8f9\n"},{"id":"242987","messageId":"1401403350-7122-5-git-send-email-gitster@pobox.com","threadId":"36787","inReplyTo":"1401403350-7122-1-git-send-email-gitster@pobox.com","subject":"[PATCH 4/5] fetch doc: on pulling multiple refspecs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-05-29T22:42:29Z","receivedAt":"2014-05-29T22:42:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Replace desription of old-style \"Pull:\" lines in remotes/\nconfiguration with modern remote.*.fetch variables.\n\nAs this note applies only to \"git pull\", enable it only\nin git-pull manual page.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/pull-fetch-param.txt | 12 ++++++++----\n 1 file changed, 8 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt\nindex e266c2d..ea4c5a6 100644\n--- a/Documentation/pull-fetch-param.txt\n+++ b/Documentation/pull-fetch-param.txt\n@@ -34,22 +34,26 @@ will be needed for such branches. There is no way to\n determine or declare that a branch will be made available\n in a repository with this behavior; the pulling user simply\n must know this is the expected usage pattern for a branch.\n+ifdef::git-pull[]\n +\n [NOTE]\n There is a difference between listing multiple \n directly on 'git pull' command line and having multiple\n-`Pull:` lines for a and running\n+`remote..fetch` entries in your configuration\n+for a and running\n 'git pull' command without any explicit parameters.\n listed explicitly on the command line are always\n merged into the current branch after fetching. In other words,\n if you list more than one remote refs, you would be making\n-an Octopus. While 'git pull' run without any explicit \n-parameter takes default s from `Pull:` lines, it\n+an Octopus merge. On the other hand, 'git pull' that is run\n+without any explicit parameter takes default\n+s from `remote..fetch` configuration, it\n merges only the first found into the current branch,\n-after fetching all the remote refs. This is because making an\n+after fetching all the remote refs specified. This is because making an\n Octopus from remote refs is rarely done, while keeping track\n of multiple remote heads in one-go by fetching more than one\n is often useful.\n+endif::git-pull[]\n +\n Some short-cut notations are also supported.\n +\n-- \n2.0.0-479-g59ac8f9\n"},{"id":"242988","messageId":"1401403350-7122-6-git-send-email-gitster@pobox.com","threadId":"36787","inReplyTo":"1401403350-7122-1-git-send-email-gitster@pobox.com","subject":"[PATCH 5/5] fetch doc: update refspec format description","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-05-29T22:42:30Z","receivedAt":"2014-05-29T22:42:30Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"The text made it sound as if the leading plus is the only thing that\nis optional, and forgot that is the same as :, i.e. fetch\nit and do not store anywhere.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/pull-fetch-param.txt | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt\nindex ea4c5a6..27cfd5c 100644\n--- a/Documentation/pull-fetch-param.txt\n+++ b/Documentation/pull-fetch-param.txt\n@@ -15,6 +15,7 @@ endif::git-pull[]\n \tThe format of a parameter is an optional plus\n \t`+`, followed by the source ref , followed\n \tby a colon `:`, followed by the destination ref .\n+\tThe colon can be omitted when is empty.\n +\n The remote ref that matches \n is fetched, and if is not empty string, the local\n-- \n2.0.0-479-g59ac8f9\n"},{"id":"243011","messageId":"5388972C.5020307@xiplink.com","threadId":"36787","inReplyTo":"1401403350-7122-2-git-send-email-gitster@pobox.com","subject":"Re: [PATCH 1/5] fetch doc: update introductory part for clarity","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2014-05-30T14:35:24Z","receivedAt":"2014-05-30T14:35:24Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 14-05-29 06:42 PM, Junio C Hamano wrote:\n> - \"Branches\" is a more common way to say \"heads\" in these days.\n> \n> - Remote-tracking branches are used a lot more these days and it is\n> worth mentioning that it is one of the primary side effects of\n> the command to update them.\n> \n> - Avoid \"X. That means Y.\" If Y is easier to understand to\n> readers, just say that upfront.\n> \n> - Use of explicit refspec to fetch tags does not have much to do\n> with turning \"auto following\" on or off. It is a way to fetch\n> tags that otherwise would not be fetched by auto-following.\n> \n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/git-fetch.txt | 29 ++++++++++++++++-------------\n> 1 file changed, 16 insertions(+), 13 deletions(-)\n> \n> diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt\n> index 5809aa4..d5f5b54 100644\n> --- a/Documentation/git-fetch.txt\n> +++ b/Documentation/git-fetch.txt\n> @@ -17,20 +17,23 @@ SYNOPSIS\n> \n> DESCRIPTION\n> -----------\n> -Fetches named heads or tags from one or more other repositories,\n> -along with the objects necessary to complete them.\n> -\n> -The ref names and their object names of fetched refs are stored\n> -in `.git/FETCH_HEAD`. This information is left for a later merge\n> -operation done by 'git merge'.\n> -\n> -By default, tags are auto-followed. This means that when fetching\n> -from a remote, any tags on the remote that point to objects that exist\n> -in the local repository are fetched. The effect is to fetch tags that\n> +Fetch branches and/or tags (collectively, \"refs\") from one or more\n> +other repositories, along with the objects necessary to complete the\n> +histories of them.\n\nPhrasing: s/the histories of them/their histories/\n\n> +\n> +The names of refs that are fetched, together with the object names\n> +they point at, are written to `.git/FETCH_HEAD`. This information\n> +is used by a later merge operation done by 'git merge'. In addition,\n\nIsn't this merge stuff about pull, not fetch?\n\n> +the remote-tracking branches may be updated (see description on\n> + below for details).\n\nI realize that \"may be updated\" is strictly correct, in that if the remote's\nbranches have not changed since the last fetch then the local tracking\nbranches won't change.\n\nBut it took me a second or two to think of that. The \"may\" kindof tripped me\nup. The fact is that the local tracking branches are always updated to match\nthe remote's branches, it's just that sometimes the remote's branches don't\nchange. So I think it would be clearer to say\n\n\tthe remote-tracking branches are updated\n\nbecause this makes it clear that the command always makes your local tracking\nbranches match the remote's.\n\n\t\tM.\n\n> +\n> +By default, any tag that points into the histories being fetched is\n> +also fetched; the effect is to fetch tags that\n> point at branches that you are interested in. This default behavior\n> -can be changed by using the --tags or --no-tags options, by\n> -configuring remote..tagopt, or by using a refspec that fetches\n> -tags explicitly.\n> +can be changed by using the --tags or --no-tags options or by\n> +configuring remote..tagopt. By using a refspec that fetches tags\n> +explicitly, you can fetch tags that do not point into branches you\n> +are interested in as well.\n> \n> 'git fetch' can fetch from either a single named repository,\n> or from several repositories at once if is given and\n> \n"},{"id":"243012","messageId":"5388972E.2010008@xiplink.com","threadId":"36787","inReplyTo":"1401403350-7122-3-git-send-email-gitster@pobox.com","subject":"Re: [PATCH 2/5] fetch doc: update note on '+' in front of the refspec","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2014-05-30T14:35:26Z","receivedAt":"2014-05-30T14:35:26Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 14-05-29 06:42 PM, Junio C Hamano wrote:\n> While it is not *wrong* per-se to say that pulling a rewound/rebased\n> branch will lead to an unnecessary merge conflict, that is not what\n> the leading \"+\" sign to allow non-fast-forward update of remote-tracking\n> branch is at all.\n> \n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/pull-fetch-param.txt | 18 +++++++++---------\n> 1 file changed, 9 insertions(+), 9 deletions(-)\n> \n> diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt\n> index 18cffc2..2a7e2b7 100644\n> --- a/Documentation/pull-fetch-param.txt\n> +++ b/Documentation/pull-fetch-param.txt\n> @@ -24,15 +24,15 @@ is updated even if it does not result in a fast-forward\n> update.\n> +\n> [NOTE]\n> -If the remote branch from which you want to pull is\n> -modified in non-linear ways such as being rewound and\n> -rebased frequently, then a pull will attempt a merge with\n> -an older version of itself, likely conflict, and fail.\n> -It is under these conditions that you would want to use\n> -the `+` sign to indicate non-fast-forward updates will\n> -be needed. There is currently no easy way to determine\n> -or declare that a branch will be made available in a\n> -repository with this behavior; the pulling user simply\n> +When the remote branch you want to fetch is known to\n> +be rewound and rebased regularly, it is expected that\n> +the tip of it will not be descendant of the commit that\n> +used to be at its tip the last time you fetched it and\n> +stored in your remote-tracking branch. You would want\n\nI think the second part of that last sentence might be clearer as\n\n\tit is expected that its new tip will not be a descendant of\n\tits previous tip (as stored in your remote-tracking branch\n\tthe last time you fetched).\n\nThen start the next sentence with\n\n\tIn this case, you would want ....\n\n\n\t\tM.\n\n> +to use the `+` sign to indicate non-fast-forward updates\n> +will be needed for such branches. There is no way to\n> +determine or declare that a branch will be made available\n> +in a repository with this behavior; the pulling user simply\n> must know this is the expected usage pattern for a branch.\n> +\n> [NOTE]\n> \n"},{"id":"243026","messageId":"xmqqioon9msf.fsf@gitster.dls.corp.google.com","threadId":"36787","inReplyTo":"5388972C.5020307@xiplink.com","subject":"Re: [PATCH 1/5] fetch doc: update introductory part for clarity","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-05-30T17:52:32Z","receivedAt":"2014-05-30T17:52:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Marc Branchaud writes:\n\n> On 14-05-29 06:42 PM, Junio C Hamano wrote:\n>> - \"Branches\" is a more common way to say \"heads\" in these days.\n>> \n>> - Remote-tracking branches are used a lot more these days and it is\n>> worth mentioning that it is one of the primary side effects of\n>> the command to update them.\n>> \n>> - Avoid \"X. That means Y.\" If Y is easier to understand to\n>> readers, just say that upfront.\n>> \n>> - Use of explicit refspec to fetch tags does not have much to do\n>> with turning \"auto following\" on or off. It is a way to fetch\n>> tags that otherwise would not be fetched by auto-following.\n>> \n>> Signed-off-by: Junio C Hamano \n>> ---\n>> Documentation/git-fetch.txt | 29 ++++++++++++++++-------------\n>> 1 file changed, 16 insertions(+), 13 deletions(-)\n>> \n>> diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt\n>> index 5809aa4..d5f5b54 100644\n>> --- a/Documentation/git-fetch.txt\n>> +++ b/Documentation/git-fetch.txt\n>> @@ -17,20 +17,23 @@ SYNOPSIS\n>> \n>> DESCRIPTION\n>> -----------\n>> -Fetches named heads or tags from one or more other repositories,\n>> -along with the objects necessary to complete them.\n>> -\n>> -The ref names and their object names of fetched refs are stored\n>> -in `.git/FETCH_HEAD`. This information is left for a later merge\n>> -operation done by 'git merge'.\n>> -\n>> -By default, tags are auto-followed. This means that when fetching\n>> -from a remote, any tags on the remote that point to objects that exist\n>> -in the local repository are fetched. The effect is to fetch tags that\n>> +Fetch branches and/or tags (collectively, \"refs\") from one or more\n>> +other repositories, along with the objects necessary to complete the\n>> +histories of them.\n>\n> Phrasing: s/the histories of them/their histories/\n\nYeah, thanks.\n\n>> +\n>> +The names of refs that are fetched, together with the object names\n>> +they point at, are written to `.git/FETCH_HEAD`. This information\n>> +is used by a later merge operation done by 'git merge'. In addition,\n>\n> Isn't this merge stuff about pull, not fetch?\n\nIt is true that \"git pull\" uses \"git fetch\" and .git/FETCH_HEAD is a\ndocumented mechanism between the two to communicate what commits the\nlatter downloaded are to be merged by the former, and that is one of\nthe reasons why we had the description here in the original before\nthis patch. A user can also do this to refer to the tip of the\nsingle branch she fetched:\n\n\tgit fetch origin master\n git log -p ..FETCH_HEAD\n git merge FETCH_HEAD\n\nPerhaps \"is used ... by 'git merge'\" can be rephrased somehow, like\n\"can be used to refer to what was fetched\"? Or we could go in the\nopposite direction and be more explicit, i.e.\n\n\t\"git pull\" calls \"git fetch\" internally, and this\n\tinformation is used by the former to learn what commits were\n\tfetched by the latter.\n\nI dunno.\n\n>> +the remote-tracking branches may be updated (see description on\n>> + below for details).\n>\n> I realize that \"may be updated\" is strictly correct, in that if the remote's\n> branches have not changed since the last fetch then the local tracking\n> branches won't change.\n>\n> But it took me a second or two to think of that. The \"may\" kindof tripped me\n> up. The fact is that the local tracking branches are always updated to match\n> the remote's branches, it's just that sometimes the remote's branches don't\n> change. So I think it would be clearer to say\n>\n> \tthe remote-tracking branches are updated\n>\n> because this makes it clear that the command always makes your local tracking\n> branches match the remote's.\n\nThe primary reason behind my \"may be\" was not \"they may not have\ndone anything in the meantime\", but was \"we may not have configured\nto track at all\", but in that case by definition we don't have \"the\nremote-tracking branches\", so now I realize that it is pointless to\nsay \"may be updated\".\n"},{"id":"243027","messageId":"xmqqegzb9mp8.fsf@gitster.dls.corp.google.com","threadId":"36787","inReplyTo":"5388972E.2010008@xiplink.com","subject":"Re: [PATCH 2/5] fetch doc: update note on '+' in front of the refspec","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-05-30T17:54:27Z","receivedAt":"2014-05-30T17:54:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Marc Branchaud writes:\n\n>> +When the remote branch you want to fetch is known to\n>> +be rewound and rebased regularly, it is expected that\n>> +the tip of it will not be descendant of the commit that\n>> +used to be at its tip the last time you fetched it and\n>> +stored in your remote-tracking branch. You would want\n>\n> I think the second part of that last sentence might be clearer as\n>\n> \tit is expected that its new tip will not be a descendant of\n> \tits previous tip (as stored in your remote-tracking branch\n> \tthe last time you fetched).\n\nYeah, that reads better. Thanks.\n\n>\n> Then start the next sentence with\n>\n> \tIn this case, you would want ....\n\nI somehow find that \"in this case\" redundant, given that \"for such\nbranches\" already limits the scope of the suggestion. I dunno.\n\n>> +to use the `+` sign to indicate non-fast-forward updates\n>> +will be needed for such branches. There is no way to\n>> +determine or declare that a branch will be made available\n>> +in a repository with this behavior; the pulling user simply\n>> must know this is the expected usage pattern for a branch.\n>> +\n>> [NOTE]\n>> \n"},{"id":"243039","messageId":"5388D857.7010705@xiplink.com","threadId":"36787","inReplyTo":"xmqqioon9msf.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH 1/5] fetch doc: update introductory part for clarity","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2014-05-30T19:13:27Z","receivedAt":"2014-05-30T19:13:27Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 14-05-30 01:52 PM, Junio C Hamano wrote:\n> Marc Branchaud writes:\n> \n>> On 14-05-29 06:42 PM, Junio C Hamano wrote:\n>>> +\n>>> +The names of refs that are fetched, together with the object names\n>>> +they point at, are written to `.git/FETCH_HEAD`. This information\n>>> +is used by a later merge operation done by 'git merge'. In addition,\n>>\n>> Isn't this merge stuff about pull, not fetch?\n> \n> It is true that \"git pull\" uses \"git fetch\" and .git/FETCH_HEAD is a\n> documented mechanism between the two to communicate what commits the\n> latter downloaded are to be merged by the former, and that is one of\n> the reasons why we had the description here in the original before\n> this patch. A user can also do this to refer to the tip of the\n> single branch she fetched:\n> \n> \tgit fetch origin master\n> git log -p ..FETCH_HEAD\n> git merge FETCH_HEAD\n> \n> Perhaps \"is used ... by 'git merge'\" can be rephrased somehow, like\n> \"can be used to refer to what was fetched\"? Or we could go in the\n> opposite direction and be more explicit, i.e.\n> \n> \t\"git pull\" calls \"git fetch\" internally, and this\n> \tinformation is used by the former to learn what commits were\n> \tfetched by the latter.\n> \n> I dunno.\n\nY'know, I've always been a bit confused by FETCH_HEAD, especially if the\nfetch updates several remote-tracking branches.\n\nThe docs say that all the fetched refs are written to FETCH_HEAD (perhaps a\nmore accurate name would have been FETCH_HEADS?). If that's truly the case,\nit seems weird to use FETCH_HEAD in log and merge commands. (My FETCH_HEAD\nfile currently has 1434 lines in it -- what does that mean, and what does it\nimply for those log and merge commands?)\n\nPerhaps FETCH_HEAD shouldn't be mentioned at all in the introductory part of\nfetch's man page.\n\n\t\tM.\n"},{"id":"243057","messageId":"xmqq61kn7yaj.fsf@gitster.dls.corp.google.com","threadId":"36787","inReplyTo":"5388D857.7010705@xiplink.com","subject":"Re: [PATCH 1/5] fetch doc: update introductory part for clarity","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-05-30T21:27:00Z","receivedAt":"2014-05-30T21:27:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Marc Branchaud writes:\n\n> The docs say that all the fetched refs are written to FETCH_HEAD (perhaps a\n> more accurate name would have been FETCH_HEADS?). If that's truly the case,\n> it seems weird to use FETCH_HEAD in log and merge commands. (My FETCH_HEAD\n> file currently has 1434 lines in it -- what does that mean, and what does it\n> imply for those log and merge commands?)\n\nThe \"fetch\" that was run by \"pull\" would have arranged the single\nremote ref that your \"pull\" merged to your then-current branch to\nthe very beginning of FETCH_HEAD, so \"git log FETCH_HEAD\" would show\nthe line of development from that ref, and \"git merge FETCH_HEAD\"\nwould also merge what your \"pull\" would have merged.\n\n> Perhaps FETCH_HEAD shouldn't be mentioned at all in the introductory part of\n> fetch's man page.\n\nA possible downside is that unreasonable people can use the lack\nof mention of FETCH_HEAD as an excuse to start making noises about\nremoving the feature.\n\nAlso, a natural way to peek into somebody else's history without\nmaking a permanent damage to your own repository, is:\n\n $ git fetch $repository_of_marc master && git log FETCH_HEAD\n\nAs such a one-shot fetch from a random place does not use (and does\nnot want to use) any remote-tracking branch, knowing that FETCH_HEAD\nis available for such a purpose would help people who want to script\nsuch a thing.\n"},{"id":"243134","messageId":"1401722507-15075-1-git-send-email-marcnarc@xiplink.com","threadId":"36787","inReplyTo":"xmqqioon9msf.fsf@gitster.dls.corp.google.com","subject":"[PATCH] fetch doc: Move FETCH_HEAD material, and add an example.","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2014-06-02T15:21:47Z","receivedAt":"2014-06-02T15:21:47Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"Signed-off-by: Marc Branchaud \n---\n Documentation/git-fetch.txt | 30 +++++++++++++++++++++---------\n 1 file changed, 21 insertions(+), 9 deletions(-)\n\nThis patch applies on top of your 1/5. It:\n\n* De-emphasizes the FETCH_HEAD stuff by moving it to the end of the\n DESCRIPTION section,\n\n* States that remote-tracking branches are simply \"updated\", and hints\n that playing with can control this.\n\n* Includes the \"their histories\" rephrasing.\n\n* Adds your peek-at-a-remote-branch example.\n\nIf you like this, feel free to sqush it into your 1/5.\n\n\t\tM.\n\n\ndiff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt\nindex d5f5b54..06106b9 100644\n--- a/Documentation/git-fetch.txt\n+++ b/Documentation/git-fetch.txt\n@@ -18,14 +18,9 @@ SYNOPSIS\n DESCRIPTION\n -----------\n Fetch branches and/or tags (collectively, \"refs\") from one or more\n-other repositories, along with the objects necessary to complete the\n-histories of them.\n-\n-The names of refs that are fetched, together with the object names\n-they point at, are written to `.git/FETCH_HEAD`. This information\n-is used by a later merge operation done by 'git merge'. In addition,\n-the remote-tracking branches may be updated (see description on\n- below for details).\n+other repositories, along with the objects necessary to complete their\n+histories. Remote-tracking branches are updated (see the description\n+of below for ways to control this behavior).\n \n By default, any tag that points into the histories being fetched is\n also fetched; the effect is to fetch tags that\n@@ -35,7 +30,7 @@ configuring remote..tagopt. By using a refspec that fetches tags\n explicitly, you can fetch tags that do not point into branches you\n are interested in as well.\n \n-'git fetch' can fetch from either a single named repository,\n+'git fetch' can fetch from either a single named repository or URL,\n or from several repositories at once if is given and\n there is a remotes. entry in the configuration file.\n (See linkgit:git-config[1]).\n@@ -43,6 +38,10 @@ there is a remotes. entry in the configuration file.\n When no remote is specified, by default the `origin` remote will be used,\n unless there's an upstream branch configured for the current branch.\n \n+The names of refs that are fetched, together with the object names\n+they point at, are written to `.git/FETCH_HEAD`. This information\n+may be used by scripts or other git commands, such as linkgit:git-pull[1].\n+\n OPTIONS\n -------\n include::fetch-options.txt[]\n@@ -79,6 +78,19 @@ the local repository by fetching from the branches (respectively)\n The `pu` branch will be updated even if it is does not fast-forward,\n because it is prefixed with a plus sign; `tmp` will not be.\n \n+* Peek at a remote's branch, without configuring the remote in your local\n+repository:\n++\n+------------------------------------------------\n+$ git fetch git://git.kernel.org/pub/scm/git/git.git maint\n+$ git log FETCH_HEAD\n+------------------------------------------------\n++\n+The first command fetches the `maint` branch from the repository at\n+`git://git.kernel.org/pub/scm/git/git.git` and the second command uses\n+`FETCH_HEAD` to examine the branch with linkgit:git-log[1]. The fetched\n+objects will eventually be removed by git's built-in housekeeping (see\n+linkgit:git-gc[1]).\n \n BUGS\n ----\n-- \n2.0.0.1.g335f86d.dirty\n"},{"id":"243135","messageId":"538C9A28.4070106@xiplink.com","threadId":"36787","inReplyTo":"xmqqegzb9mp8.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH 2/5] fetch doc: update note on '+' in front of the refspec","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2014-06-02T15:37:12Z","receivedAt":"2014-06-02T15:37:12Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 14-05-30 01:54 PM, Junio C Hamano wrote:\n> Marc Branchaud writes:\n>>\n>> Then start the next sentence with\n>>\n>> \tIn this case, you would want ....\n> \n> I somehow find that \"in this case\" redundant, given that \"for such\n> branches\" already limits the scope of the suggestion. I dunno.\n\nI shrug in indifference. Toh-may-toe, poh-tah-toe...\n\n\t\tM.\n"},{"id":"243143","messageId":"xmqqbnub5fvk.fsf@gitster.dls.corp.google.com","threadId":"36787","inReplyTo":"1401722507-15075-1-git-send-email-marcnarc@xiplink.com","subject":"Re: [PATCH] fetch doc: Move FETCH_HEAD material, and add an example.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-06-02T18:24:31Z","receivedAt":"2014-06-02T18:24:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Marc Branchaud writes:\n\n> Signed-off-by: Marc Branchaud \n> ---\n> Documentation/git-fetch.txt | 30 +++++++++++++++++++++---------\n> 1 file changed, 21 insertions(+), 9 deletions(-)\n>\n> This patch applies on top of your 1/5. It:\n>\n> * De-emphasizes the FETCH_HEAD stuff by moving it to the end of the\n> DESCRIPTION section,\n\nThis reads much better. Thanks.\n\n>\n> * States that remote-tracking branches are simply \"updated\", and hints\n> that playing with can control this.\n>\n> * Includes the \"their histories\" rephrasing.\n>\n> * Adds your peek-at-a-remote-branch example.\n\n> If you like this, feel free to sqush it into your 1/5.\n\nWill splice in as patch 1.5 instead ;-)\n"}]}