{"thread":{"id":"12126","subject":"[PATCH] Correct git-pull documentation","startedAt":"2008-02-16T04:50:41Z","lastAt":"2008-02-16T10:04:20Z","messageCount":4,"participants":["Jay Soffian","Nagy Balázs","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"68865","messageId":"1203137441-52448-1-git-send-email-jaysoffian@gmail.com","threadId":"12126","inReplyTo":null,"subject":"[PATCH] Correct git-pull documentation","fromName":"Jay Soffian","fromEmail":"jaysoffian@gmail.com","sentAt":"2008-02-16T04:50:41Z","receivedAt":"2008-02-16T04:50:41Z","isPatch":true,"sender":{"key":"jaysoffian@gmail.com","avatar":"https://avatars.githubusercontent.com/u/155970?v=4"},"body":"The --rebase option was documented in the wrong place (under MERGE\nSTRATEGIES instead of OPTIONS). Noted the branch..rebase\noption and clarified the use '.' in a few places. Switched\n\"git-\" to \"git command\".\n\nSigned-off-by: Jay Soffian \n---\n Documentation/git-pull.txt | 38 ++++++++++++++++++++++----------------\n 1 files changed, 22 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\nindex 179bdfc..f734f18 100644\n--- a/Documentation/git-pull.txt\n+++ b/Documentation/git-pull.txt\n@@ -8,13 +8,14 @@ git-pull - Fetch from and merge with another repository or a local branch\n \n SYNOPSIS\n --------\n-'git-pull' ...\n+'git-pull' [] [] [...]\n \n \n DESCRIPTION\n -----------\n-Runs `git-fetch` with the given parameters, and calls `git-merge`\n-to merge the retrieved head(s) into the current branch.\n+Runs `git fetch` with the given parameters, and calls `git merge` or\n+`git rebase` to merge or rebase the retrieved head(s) into the\n+current branch.\n \n Note that you can use `.` (current directory) as the\n to pull from the local repository -- this is useful\n@@ -28,17 +29,12 @@ include::merge-options.txt[]\n :git-pull: 1\n include::fetch-options.txt[]\n \n-include::pull-fetch-param.txt[]\n-\n-include::urls-remotes.txt[]\n-\n-include::merge-strategies.txt[]\n-\n \\--rebase::\n \tInstead of a merge, perform a rebase after fetching. If\n \tthere is a remote ref for the upstream branch, and this branch\n \twas rebased since last fetched, the rebase uses that information\n-\tto avoid rebasing non-local changes.\n+\tto avoid rebasing non-local changes. This if the default if\n+\t`branch..rebase` is set.\n +\n *NOTE:* This is a potentially _dangerous_ mode of operation.\n It rewrites history, which does not bode well when you\n@@ -48,6 +44,12 @@ unless you have read linkgit:git-rebase[1] carefully.\n \\--no-rebase::\n \tOverride earlier \\--rebase.\n \n+include::pull-fetch-param.txt[]\n+\n+include::urls-remotes.txt[]\n+\n+include::merge-strategies.txt[]\n+\n DEFAULT BEHAVIOUR\n -----------------\n \n@@ -55,12 +57,13 @@ Often people use `git pull` without giving any parameter.\n Traditionally, this has been equivalent to saying `git pull\n origin`. However, when configuration `branch..remote` is\n present while on branch ``, that value is used instead of\n-`origin`.\n+`origin`. (`branch..remote` may be set to `.` to pull from \n+the local repository by default.)\n \n-In order to determine what URL to use to fetch from, the value\n-of the configuration `remote..url` is consulted\n-and if there is not any such variable, the value on `URL: ` line\n-in `$GIT_DIR/remotes/` file is used.\n+Unless pulling from the local repository, a URL must be determined\n+for the origin. This is done by first consulting\n+`remote..url`. If there is not any such variable, the value\n+on `URL: ` line in `$GIT_DIR/remotes/` file is used.\n \n In order to determine what remote branches to fetch (and\n optionally store in the tracking branches) when the command is\n@@ -138,6 +141,9 @@ You should refrain from abusing this option to sneak substantial\n changes into a merge commit. Small fixups like bumping\n release/version name would be acceptable.\n \n+git pull --rebase . master::\n+\tThis syntax is equivalent to calling `git rebase master`; see\n+\tlinkgit:git-rebase[1] for details.\n Command line pull of multiple branches from one repository::\n +\n ------------------------------------------------\n@@ -163,7 +169,7 @@ linkgit:git-reset[1].\n \n SEE ALSO\n --------\n-linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-config[1]\n+linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-config[1], linkgit:git-rebase[1]\n \n \n Author\n-- \n1.5.4.1.1281.g75df\n"},{"id":"68886","messageId":"47B69CDB.7070908@iksz.hu","threadId":"12126","inReplyTo":"1203137441-52448-1-git-send-email-jaysoffian@gmail.com","subject":"Re: [PATCH] Correct git-pull documentation","fromName":"Nagy Balázs","fromEmail":"js@iksz.hu","sentAt":"2008-02-16T08:20:43Z","receivedAt":"2008-02-16T08:20:43Z","isPatch":true,"sender":{"key":"js@iksz.hu","avatar":"https://gravatar.com/avatar/8e618db1f4a022c12a6f0cd5a9632663f61afd781108fdf32f2433589b1901b8?d=mp&s=160"},"body":"Jay Soffian wrote:\n> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\n> index 179bdfc..f734f18 100644\n> --- a/Documentation/git-pull.txt\n> +++ b/Documentation/git-pull.txt\n> \n...\n> @@ -28,17 +29,12 @@ include::merge-options.txt[]\n> :git-pull: 1\n> include::fetch-options.txt[]\n> \n> -include::pull-fetch-param.txt[]\n> -\n> -include::urls-remotes.txt[]\n> -\n> -include::merge-strategies.txt[]\n> -\n> \\--rebase::\n> \tInstead of a merge, perform a rebase after fetching. If\n> \tthere is a remote ref for the upstream branch, and this branch\n> \twas rebased since last fetched, the rebase uses that information\n> -\tto avoid rebasing non-local changes.\n> +\tto avoid rebasing non-local changes. This if the default if\n> \n... This *is* the default if\n> +\t`branch..rebase` is set.\n> +\n> *NOTE:* This is a potentially _dangerous_ mode of operation.\n> It rewrites history, which does not bode well when you\n> \n-- \n-jul-\n"},{"id":"68891","messageId":"7vodahb63s.fsf@gitster.siamese.dyndns.org","threadId":"12126","inReplyTo":"1203137441-52448-1-git-send-email-jaysoffian@gmail.com","subject":"Re: [PATCH] Correct git-pull documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-02-16T09:31:03Z","receivedAt":"2008-02-16T09:31:03Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jay Soffian writes:\n\n> The --rebase option was documented in the wrong place (under MERGE\n> STRATEGIES instead of OPTIONS). Noted the branch..rebase\n> option and clarified the use '.' in a few places. Switched\n> \"git-\" to \"git command\".\n\nClarifying that --rebase is not a strategy is a good\nimprovement. Thanks.\n\n> @@ -55,12 +57,13 @@ Often people use `git pull` without giving any parameter.\n> Traditionally, this has been equivalent to saying `git pull\n> origin`. However, when configuration `branch..remote` is\n> present while on branch ``, that value is used instead of\n> -`origin`.\n> +`origin`. (`branch..remote` may be set to `.` to pull from \n> +the local repository by default.)\n\nI am not sure if this special case deserves mentioning here.\n\n> -In order to determine what URL to use to fetch from, the value\n> -of the configuration `remote..url` is consulted\n> -and if there is not any such variable, the value on `URL: ` line\n> -in `$GIT_DIR/remotes/` file is used.\n> +Unless pulling from the local repository, a URL must be determined\n> +for the origin. This is done by first consulting\n> +`remote..url`. If there is not any such variable, the value\n> +on `URL: ` line in `$GIT_DIR/remotes/` file is used.\n\nLikewise.\n\n> @@ -138,6 +141,9 @@ You should refrain from abusing this option to sneak substantial\n> changes into a merge commit. Small fixups like bumping\n> release/version name would be acceptable.\n> \n> +git pull --rebase . master::\n> +\tThis syntax is equivalent to calling `git rebase master`; see\n> +\tlinkgit:git-rebase[1] for details.\n\nLikewise. That is a very roundabout way to say \"git rebase\nmaster\". It happens to work as a logical consequence of two\nfacts (1) that you can pull from any remote and (2) that \".\" is\na valid remote that names local. I am personally happy that the\ncommand works consistently, but I think we should rather teach\npeople the more natural way to do their rebase in our\ndocumentation.\n\nThe fact that we earlier talked about \"git pull .\" does not\njustify this addition. Even though \"git pull .\" is also a\nroundabout way, it used to be the only way (we did not have the\n\"git merge\" callable as the top-level command) and there are\nexisting documents that show the \"git pull .\" form out there on\nthe web, and that is the primary reason we mention this ancient\nform, so that people who saw such an ancient notation can find\nout what it is about in our documentation. Some people still\nprefer it from pure inertia, and we have no reason to deprecate\nit, but I do not think it is something we should advertise as\nthe first class interface.\n"},{"id":"68893","messageId":"76718490802160204x348af397i8bda3abb9dd04b0c@mail.gmail.com","threadId":"12126","inReplyTo":"7vodahb63s.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Correct git-pull documentation","fromName":"Jay Soffian","fromEmail":"jaysoffian@gmail.com","sentAt":"2008-02-16T10:04:20Z","receivedAt":"2008-02-16T10:04:20Z","isPatch":true,"sender":{"key":"jaysoffian@gmail.com","avatar":"https://avatars.githubusercontent.com/u/155970?v=4"},"body":"On Feb 16, 2008 4:31 AM, Junio C Hamano wrote:\n> Jay Soffian writes:\n>\n> > The --rebase option was documented in the wrong place (under MERGE\n> > STRATEGIES instead of OPTIONS). Noted the branch..rebase\n> > option and clarified the use '.' in a few places. Switched\n> > \"git-\" to \"git command\".\n>\n> Clarifying that --rebase is not a strategy is a good\n> improvement. Thanks.\n>\n> > @@ -55,12 +57,13 @@ Often people use `git pull` without giving any parameter.\n> > Traditionally, this has been equivalent to saying `git pull\n> > origin`. However, when configuration `branch..remote` is\n> > present while on branch ``, that value is used instead of\n> > -`origin`.\n> > +`origin`. (`branch..remote` may be set to `.` to pull from\n> > +the local repository by default.)\n>\n> I am not sure if this special case deserves mentioning here.\n\nSigh, this is getting a bit frustrating. Yes you can use \"fetch + merge\" or\n\"fetch + rebase\", but what I'm trying to get at here is that if the user\nconfigures their branch appropriately, they can just use \"git pull\" and it\nwill just Do The Right Thing. But for that to work, the user has to know to\nset branch..remote to \".\" and the git-pull documentation seems like the\nright place to mention it.\n\n> > -In order to determine what URL to use to fetch from, the value\n> > -of the configuration `remote..url` is consulted\n> > -and if there is not any such variable, the value on `URL: ` line\n> > -in `$GIT_DIR/remotes/` file is used.\n> > +Unless pulling from the local repository, a URL must be determined\n> > +for the origin. This is done by first consulting\n> > +`remote..url`. If there is not any such variable, the value\n> > +on `URL: ` line in `$GIT_DIR/remotes/` file is used.\n>\n> Likewise.\n\nLikewise what? All I did was clarify the existing paragraph which was wrong in\nthe case where remote is set to \".\"\n\n> > @@ -138,6 +141,9 @@ You should refrain from abusing this option to sneak substantial\n> > changes into a merge commit. Small fixups like bumping\n> > release/version name would be acceptable.\n> >\n> > +git pull --rebase . master::\n> > + This syntax is equivalent to calling `git rebase master`; see\n> > + linkgit:git-rebase[1] for details.\n>\n> Likewise. That is a very roundabout way to say \"git rebase\n> master\". It happens to work as a logical consequence of two\n> facts (1) that you can pull from any remote and (2) that \".\" is\n> a valid remote that names local. I am personally happy that the\n> command works consistently, but I think we should rather teach\n> people the more natural way to do their rebase in our\n> documentation.\n>\n> The fact that we earlier talked about \"git pull .\" does not\n> justify this addition. Even though \"git pull .\" is also a\n> roundabout way, it used to be the only way (we did not have the\n> \"git merge\" callable as the top-level command) and there are\n> existing documents that show the \"git pull .\" form out there on\n> the web, and that is the primary reason we mention this ancient\n> form, so that people who saw such an ancient notation can find\n> out what it is about in our documentation. Some people still\n> prefer it from pure inertia, and we have no reason to deprecate\n> it, but I do not think it is something we should advertise as\n> the first class interface.\n\nI want to be able to use \"git pull\" (w/o any options) and have it figure out\nbased on my configuration what to do with the current branch, be it:\n\n1. merge another local branch.\n1. rebase from another local branch.\n3. fetch+merge from remote.\n4. fetch+rebase from remote.\n\nAnd in fact, I can. But to do so, I have to know that \".\" means local, so why\nnot advertise that fact in git-pull?\n\nj.\n"}]}