* [DOC-PATCH] Clarify description of <repository> argument to pull/fetch for naming remotes. @ 2008-05-28 14:59 John J. Franey 2008-05-28 19:21 ` Junio C Hamano 0 siblings, 1 reply; 3+ messages in thread From: John J. Franey @ 2008-05-28 14:59 UTC (permalink / raw) To: git, gitster Signed-off-by: John J. Franey <jjfraney@gmail.com> --- Here is proposal for the git-fetch(1) and git-pull(1) man pages. As a newbie, I found the original a bit too awkward to understand readily. I hope this is helpful. Alter description of <repository> in OPTIONS section to explicitly state that a 'remote name' is accepted. Rewrite REMOTES section to more directly identify the different kinds of remotes permitted. Documentation/pull-fetch-param.txt | 4 ++- Documentation/urls-remotes.txt | 65 ++++++++++++++++++++--------------- 2 files changed, 40 insertions(+), 29 deletions(-) diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt index b6eb7fc..cbee369 100644 --- a/Documentation/pull-fetch-param.txt +++ b/Documentation/pull-fetch-param.txt @@ -1,6 +1,8 @@ <repository>:: The "remote" repository that is the source of a fetch - or pull operation. See the section <<URLS,GIT URLS>> below. + or pull operation. This parameter can be either a URL + (see the section <<URLS,GIT URLS>> below) or the name + of a remote (see the section <<REMOTES,REMOTES>> below). <refspec>:: The canonical format of a <refspec> parameter is diff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.txt index 5dd1f83..31e542d 100644 --- a/Documentation/urls-remotes.txt +++ b/Documentation/urls-remotes.txt @@ -1,11 +1,21 @@ include::urls.txt[] -REMOTES -------- +REMOTES[[REMOTES]] +------------------ -In addition to the above, as a short-hand, the name of a -file in `$GIT_DIR/remotes` directory can be given; the -named file should be in the following format: +The name of one of the following can be used instead of a URL as <repository> argument: + +* a file in the `$GIT_DIR/remotes` directory, +* a remote in the git configuration file: `$GIT_DIR/config`, or +* a file in the `$GIT_DIR/branches` directory. + + + +Named files in `$GIT_DIR/remotes` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If <repository> is the name of a file in the `$GIT_DIR/remotes` directory, +the file should have the following format: ------------ URL: one of the above URL format @@ -14,15 +24,16 @@ named file should be in the following format: ------------ -Then such a short-hand is specified in place of -<repository> without <refspec> parameters on the command -line, <refspec> specified on `Push:` lines or `Pull:` -lines are used for `git-push` and `git-fetch`/`git-pull`, -respectively. Multiple `Push:` and `Pull:` lines may +`Push:` lines are used by `git-push` and +`Pull:` lines are used by `git-pull` and `git-fetch`. +Multiple `Push:` and `Pull:` lines may be specified for additional branch mappings. -Or, equivalently, in the `$GIT_DIR/config` (note the use -of `fetch` instead of `Pull:`): +Named remote in configuration file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If <repository> is the name of a remote entry in the git configuration file, +the entry might look like this: ------------ [remote "<remote>"] @@ -32,24 +43,22 @@ of `fetch` instead of `Pull:`): ------------ -The name of a file in `$GIT_DIR/branches` directory can be -specified as an older notation short-hand; the named -file should contain a single line, a URL in one of the -above formats, optionally followed by a hash `#` and the -name of remote head (URL fragment notation). -`$GIT_DIR/branches/<remote>` file that stores a <url> -without the fragment is equivalent to have this in the -corresponding file in the `$GIT_DIR/remotes/` directory. +Note the use of `fetch` instead of `Pull:` (a distinction from the format described above). +See linkgit:git-remote[1] or linkgit:git-config[1] for details. ------------- - URL: <url> - Pull: refs/heads/master:<remote> - ------------- +Named file in `$GIT_DIR/branches` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -while having `<url>#<head>` is equivalent to +If <repository> is the name of a file in the `$GIT_DIR/branches` directory, +the file should have the following format, +on a single line: ------------ - URL: <url> - Pull: refs/heads/<head>:<remote> + <url>#<head> ------------ + +This line contains a URL in one of the above formats, +optionally followed by a hash `#` and the +name of remote head (URL fragment notation). +'master' is default in case the hash and remote head are omitted. + -- 1.5.4.3 ^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [DOC-PATCH] Clarify description of <repository> argument to pull/fetch for naming remotes. 2008-05-28 14:59 [DOC-PATCH] Clarify description of <repository> argument to pull/fetch for naming remotes John J. Franey @ 2008-05-28 19:21 ` Junio C Hamano 2008-05-29 1:43 ` John J. Franey 0 siblings, 1 reply; 3+ messages in thread From: Junio C Hamano @ 2008-05-28 19:21 UTC (permalink / raw) To: John J. Franey; +Cc: git "John J. Franey" <jjfraney@gmail.com> writes: > Signed-off-by: John J. Franey <jjfraney@gmail.com> > --- > Here is proposal for the git-fetch(1) and git-pull(1) > man pages. As a newbie, I found the original a bit > too awkward to understand readily. I hope this is > helpful. While I do like making visual distinction to separate different things into different sections as a general rule (unless each section ends up with too little information), I think this is almost on the borderline. > Alter description of <repository> in OPTIONS section to > explicitly state that a 'remote name' is accepted. > > Rewrite REMOTES section to more directly identify the > different kinds of remotes permitted. I think you meant to place these two paragraphs in the commit log message, so they should come before your Sign-off and three-dash lines. > Documentation/pull-fetch-param.txt | 4 ++- > Documentation/urls-remotes.txt | 65 ++++++++++++++++++++--------------- > 2 files changed, 40 insertions(+), 29 deletions(-) > > diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt > index b6eb7fc..cbee369 100644 > --- a/Documentation/pull-fetch-param.txt > +++ b/Documentation/pull-fetch-param.txt > @@ -1,6 +1,8 @@ > <repository>:: > The "remote" repository that is the source of a fetch > - or pull operation. See the section <<URLS,GIT URLS>> below. > + or pull operation. This parameter can be either a URL > + (see the section <<URLS,GIT URLS>> below) or the name > + of a remote (see the section <<REMOTES,REMOTES>> below). Ok, I often see this referred to as "short-hand" or "nickname", but you chose to use "the name of a remote", which is more descriptive. > diff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.txt > index 5dd1f83..31e542d 100644 > --- a/Documentation/urls-remotes.txt > +++ b/Documentation/urls-remotes.txt > @@ -1,11 +1,21 @@ > include::urls.txt[] > > -REMOTES > -------- > +REMOTES[[REMOTES]] > +------------------ > > -In addition to the above, as a short-hand, the name of a > -file in `$GIT_DIR/remotes` directory can be given; the > -named file should be in the following format: > +The name of one of the following can be used instead of a URL as <repository> argument: > + > +* a file in the `$GIT_DIR/remotes` directory, > +* a remote in the git configuration file: `$GIT_DIR/config`, or > +* a file in the `$GIT_DIR/branches` directory. Ok. However, because a remote configured in the configuration file takes precedence (it is the youngest invention) over $GIT_DIR/remotes/ which in turn takes precedence over $GIT_DIR/branches/, we probably would want to move the bullet list and the sections around to talk about the config first, then remotes, and then finally branches, in this document. > +Named files in `$GIT_DIR/remotes` > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > + > +If <repository> is the name of a file in the `$GIT_DIR/remotes` directory, > +the file should have the following format: This also sounds somewhat awkward to me. "If you do X, Y has to be Z" has a funny connotation that "On the other hand, if you don't, Y does not have to follow this rule", but that is not what is going on here. We only want to say "You could choose to do X, and here are the rules..." So how about... You can use a file in `$GIT_DIR/remotes/<remote>` to name the remote repository <remote>. The file should be in the following format: Same comment applies to other two sections. > @@ -14,15 +24,16 @@ named file should be in the following format: > > ------------ > > -Then such a short-hand is specified in place of > -<repository> without <refspec> parameters on the command > -line, <refspec> specified on `Push:` lines or `Pull:` > -lines are used for `git-push` and `git-fetch`/`git-pull`, > -respectively. Multiple `Push:` and `Pull:` lines may > +`Push:` lines are used by `git-push` and > +`Pull:` lines are used by `git-pull` and `git-fetch`. > +Multiple `Push:` and `Pull:` lines may > be specified for additional branch mappings. I see that the original has a typo "s/Then/When/". The rewrite drops an important piece of information that these Push/Pull lines take effect _only when_ the nickname (eh, "the name of the remote") is given on the command line without explicit refspecs. > +Named remote in configuration file > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > + > +If <repository> is the name of a remote entry in the git configuration file, > +the entry might look like this: Similarly... A `[remote "<remote>"]` section in the configuration file can be used to name the remote. The section will look like this: > ------------ > [remote "<remote>"] In addition... Similar to the `$GIT_DIR/remotes/<repository>` push/fetch give the default refspecs when none is given on the command line. > +Note the use of `fetch` instead of `Pull:` (a distinction from the format described above). > +See linkgit:git-remote[1] or linkgit:git-config[1] for details. Iff you really need to stress mismatch, after reordering the sections, you could point out that `$GIT_DIR/remotes` file uses "Pull" instead of more natural "fetch", which is a historical accident. ^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [DOC-PATCH] Clarify description of <repository> argument to pull/fetch for naming remotes. 2008-05-28 19:21 ` Junio C Hamano @ 2008-05-29 1:43 ` John J. Franey 0 siblings, 0 replies; 3+ messages in thread From: John J. Franey @ 2008-05-29 1:43 UTC (permalink / raw) To: Junio C Hamano; +Cc: git On Wed, 2008-05-28 at 12:21 -0700, Junio C Hamano wrote: > "John J. Franey" <jjfraney@gmail.com> writes: > > > Signed-off-by: John J. Franey <jjfraney@gmail.com> > > --- > > Here is proposal for the git-fetch(1) and git-pull(1) > > man pages. As a newbie, I found the original a bit > > too awkward to understand readily. I hope this is > > helpful. > > While I do like making visual distinction to separate different things > into different sections as a general rule (unless each section ends up > with too little information), I think this is almost on the borderline. > > Alter description of <repository> in OPTIONS section to > > explicitly state that a 'remote name' is accepted. > > > > Rewrite REMOTES section to more directly identify the > > different kinds of remotes permitted. > > I think you meant to place these two paragraphs in the commit log message, > so they should come before your Sign-off and three-dash lines. I didn't mean to put these in the commit log message. I will if that is what you are recommending me to do. These comments were only meant to explain the changes to you and others on the mailing list. > > > Documentation/pull-fetch-param.txt | 4 ++- > > Documentation/urls-remotes.txt | 65 ++++++++++++++++++++--------------- > > 2 files changed, 40 insertions(+), 29 deletions(-) > > > > diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt > > index b6eb7fc..cbee369 100644 > > --- a/Documentation/pull-fetch-param.txt > > +++ b/Documentation/pull-fetch-param.txt > > @@ -1,6 +1,8 @@ > > <repository>:: > > The "remote" repository that is the source of a fetch > > - or pull operation. See the section <<URLS,GIT URLS>> below. > > + or pull operation. This parameter can be either a URL > > + (see the section <<URLS,GIT URLS>> below) or the name > > + of a remote (see the section <<REMOTES,REMOTES>> below). > > Ok, I often see this referred to as "short-hand" or "nickname", but you > chose to use "the name of a remote", which is more descriptive. 'name of a remote' is meant to draw connection with the parameter 'name' of 'git-remote(1)', and the config variables 'remote.<name>.*' described in 'git-config(1)'. 'short-hand' and 'nickname' are correct but didn't lead me to recognize that its the same as git-remotes's <name>. The light came on when I finally saw that 'short-hand' wasn't actually an abbreviation or alternate name, but really *the very* name of a file or remote (which git reads/access to obtain a URL). > > > diff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.txt > > index 5dd1f83..31e542d 100644 > > --- a/Documentation/urls-remotes.txt > > +++ b/Documentation/urls-remotes.txt > > @@ -1,11 +1,21 @@ > > include::urls.txt[] > > > > -REMOTES > > -------- > > +REMOTES[[REMOTES]] > > +------------------ > > > > -In addition to the above, as a short-hand, the name of a > > -file in `$GIT_DIR/remotes` directory can be given; the > > -named file should be in the following format: > > +The name of one of the following can be used instead of a URL as <repository> argument: > > + > > +* a file in the `$GIT_DIR/remotes` directory, > > +* a remote in the git configuration file: `$GIT_DIR/config`, or > > +* a file in the `$GIT_DIR/branches` directory. > > Ok. However, because a remote configured in the configuration file takes > precedence (it is the youngest invention) over $GIT_DIR/remotes/ which in > turn takes precedence over $GIT_DIR/branches/, we probably would want to > move the bullet list and the sections around to talk about the config > first, then remotes, and then finally branches, in this document. > Will do. > > +Named files in `$GIT_DIR/remotes` > > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > + > > +If <repository> is the name of a file in the `$GIT_DIR/remotes` directory, > > +the file should have the following format: > > This also sounds somewhat awkward to me. "If you do X, Y has to be Z" has > a funny connotation that "On the other hand, if you don't, Y does not have > to follow this rule", but that is not what is going on here. We only want > to say "You could choose to do X, and here are the rules..." So how > about... > > You can use a file in `$GIT_DIR/remotes/<remote>` to name the remote > repository <remote>. The file should be in the following format: > > Same comment applies to other two sections. Ok. I see what you mean. I'm striving to retain the connection that <repository> is in fact the name of the remote in config file, or the name of a file (in either directory). How about: -- configured remotes section -- You can provide the name of a remote which you had previously configured using git-remote(1), git-config(1) or even by an edit to the `$GIT_DIR/config` file. See <link to man pages> for details. The entry in the config file would appear like this: --- remotes directory section -- You can provide the name of a file in `$GIT_DIR/remotes`. The file would contain the URL of the remote repository and should have the following format: --- branches section -- You can provide the name of a file in `$GID_DIR/branches`. The file would contain the URL of the remote repository and should have the following format: > > > @@ -14,15 +24,16 @@ named file should be in the following format: > > > > ------------ > > > > -Then such a short-hand is specified in place of > > -<repository> without <refspec> parameters on the command > > -line, <refspec> specified on `Push:` lines or `Pull:` > > -lines are used for `git-push` and `git-fetch`/`git-pull`, > > -respectively. Multiple `Push:` and `Pull:` lines may > > +`Push:` lines are used by `git-push` and > > +`Pull:` lines are used by `git-pull` and `git-fetch`. > > +Multiple `Push:` and `Pull:` lines may > > be specified for additional branch mappings. > > I see that the original has a typo "s/Then/When/". > > The rewrite drops an important piece of information that these Push/Pull > lines take effect _only when_ the nickname (eh, "the name of the remote") > is given on the command line without explicit refspecs. > ok; will restore that information. > > +Named remote in configuration file > > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > + > > +If <repository> is the name of a remote entry in the git configuration file, > > +the entry might look like this: > > Similarly... > > A `[remote "<remote>"]` section in the configuration file can be used to > name the remote. The section will look like this: > > ------------ > > [remote "<remote>"] > > In addition... > > Similar to the `$GIT_DIR/remotes/<repository>` push/fetch give the > default refspecs when none is given on the command line. > OK. Got it. > > +Note the use of `fetch` instead of `Pull:` (a distinction from the format described above). > > +See linkgit:git-remote[1] or linkgit:git-config[1] for details. > > Iff you really need to stress mismatch, after reordering the sections, you > could point out that `$GIT_DIR/remotes` file uses "Pull" instead of more > natural "fetch", which is a historical accident. > OK. Will do. If you don't think the mismatch needs to be stressed, I can remove it altogether. I don't think the emphasis is needed. Thank you for taking the time to look at this. Regards, John ^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2008-05-29 1:44 UTC | newest] Thread overview: 3+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2008-05-28 14:59 [DOC-PATCH] Clarify description of <repository> argument to pull/fetch for naming remotes John J. Franey 2008-05-28 19:21 ` Junio C Hamano 2008-05-29 1:43 ` John J. Franey
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox