* [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