On Wed, 2008-05-28 at 12:21 -0700, Junio C Hamano wrote: > "John J. Franey" <jjfraney@xxxxxxxxx> writes: > > > Signed-off-by: John J. Franey <jjfraney@xxxxxxxxx> > > --- > > 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
