[PATCH v4] Documentation/remote-helpers: Add invocation section

[PATCH v4] Documentation/remote-helpers: Add invocation section

[Ramkumar Ramachandra]

Add an invocation section to specify what the command line arguments
mean. Also include a link to git-remote in the see also section.

Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 What changed since v3: Clarification on what URLs can be, and
 possibility of second argument making the first redundant.

 Documentation/git-remote-helpers.txt |   18 ++++++++++++++++++
 1 files changed, 18 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-remote-helpers.txt
b/Documentation/git-remote-helpers.txt
index 2382fb4..f2b2738 100644
--- a/Documentation/git-remote-helpers.txt
+++ b/Documentation/git-remote-helpers.txt
@@ -38,6 +38,20 @@ Git comes with a "curl" family of remote helpers,
specifically
 'git-remote-ftps'. They implement the capabilities 'fetch', 'option',
 and 'push'.

+INVOCATION
+----------
+
+Remote helper programs are invoked with one or (optionally) two
+command line arguments. The first argument specifies a remote
+repository as in git; typically, it is either the name of a configured
+remote or just a URL. The second argument, if present, is a URL. When
+the remote specified in the first argument has more than one
+configured URL, it serves to resolve the ambiguity and pick one of the
+URLs. Depending on the remote helper, supplying the second argument
+can make the first argument redundant. URLs may be those normally
+recognized by git, or arbitrary URL-like strings recognized by the
+specific remote helper being invoked.
+
 COMMANDS
 --------

@@ -206,6 +220,10 @@ OPTIONS
 	must not rely on this option being set before
 	connect request occurs.

+SEE ALSO
+--------
+linkgit:git-remote[1]
+
 Documentation
 -------------
 Documentation by Daniel Barkalow and Ilari Liusvaara
-- 
1.7.0.3

Re: [PATCH v4] Documentation/remote-helpers: Add invocation section

[Junio C Hamano]

Ramkumar Ramachandra <artagnon@gmail.com> writes:

> Add an invocation section to specify what the command line arguments
> mean. Also include a link to git-remote in the see also section.
>
> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
> ---
>  What changed since v3: Clarification on what URLs can be, and
>  possibility of second argument making the first redundant.
>
>  Documentation/git-remote-helpers.txt |   18 ++++++++++++++++++
>  1 files changed, 18 insertions(+), 0 deletions(-)
>
> diff --git a/Documentation/git-remote-helpers.txt
> b/Documentation/git-remote-helpers.txt
> index 2382fb4..f2b2738 100644
> --- a/Documentation/git-remote-helpers.txt
> +++ b/Documentation/git-remote-helpers.txt
> @@ -38,6 +38,20 @@ Git comes with a "curl" family of remote helpers,
> specifically
>  'git-remote-ftps'. They implement the capabilities 'fetch', 'option',
>  and 'push'.
>
> +INVOCATION
> +----------
> +
> +Remote helper programs are invoked with one or (optionally) two
> +command line arguments. The first argument specifies a remote
> +repository as in git; typically, it is either the name of a configured
> +remote or just a URL. The second argument, if present, is a URL. When
> +the remote specified in the first argument has more than one
> +configured URL, it serves to resolve the ambiguity and pick one of the
> +URLs. Depending on the remote helper, supplying the second argument
> +can make the first argument redundant. URLs may be those normally
> +recognized by git, or arbitrary URL-like strings recognized by the
> +specific remote helper being invoked.
> +

What is the target audience of this paragraph?  You would need to keep
these questions in mind, depending on what your target audience is:

 - As a potential developer for a new "remote helper", how would one be
   helped by this description?

 - As a user of non-native transport served by a remote helper, how would
   one be helped by this description?

Suppose I am writing a remote helper 'frotz' to interact with the frotz
SCM.  What are the things I need to know about the remote-helper
mechanism?

 - I will write "git-remote-frotz"; it will need to be told which
   "repository" in native frotz SCM format the program should interact
   with, and that information would eventually come from the end users.

   By the way, is this even clear in the existing documentation?

 - The user will somehow specify that 'frotz' helper is called for the
   repository.  Perhaps "git clone frotz::<some info>" will create a new
   git repository and leave enough information in its .git/config so that
   later "git fetch" or "git pull" will automatically know that the name
   'origin' refers to my 'frotz' helper, and <some info> is passed to my
   "git-remote-frotz" program in some way.

   During the initial cloning, my 'frotz' helper will be called and will
   be given <some info> so that it can interact with the remote before
   having enough information in .git/config, perhaps.

   "git remote add mine frotz::<some info>" would leave similar kind of
   information in .git/config so that the nickname 'mine' refers to my
   'frotz' helper, and <some info> is passed to my "git-remote-frotz"
   program in some way, hopefully the same way as the above.

   Or "git fetch frotz::<some info>" from the command line may be used
   without any additional information from .git/config and would call my
   "git-fermote-frotz" with <some info>.

This INVOCATION section needs to spell out exact details of how that <some
info> is given to git-remote-frotz, so that I can decide how to encode the
repository information the program would use.

With some transports like the p4 example given in earlier discussion,
perhaps a single token that can be given from the command line may not
be sufficient to identify a foreign repository, in which case <some
info> might be just 'p4' and I would need to look up 'p4.origin.*' for
additional information on my own.  The details of p4 implementation does
not have to be spelled out in this INVOCATIONS section, but it needs to
hint the possibility of doing something like that.

I would think that INVOCATION section needs to specify how the helper is
selected (e.g. taking "frotz" out of "frotz::<some info>", or using the
configuration variable remote.origin.vcs), and where the one or two
parameters given to the program come from, to help such a developer who
wants to add his own remote helper.

Re: [PATCH v4] Documentation/remote-helpers: Add invocation section

[Ramkumar Ramachandra]

Hi,

On Tue, Apr 6, 2010 at 4:31 AM, Junio C Hamano <gitster@pobox.com> wrote:
> I would think that INVOCATION section needs to specify how the helper is
> selected (e.g. taking "frotz" out of "frotz::<some info>", or using the
> configuration variable remote.origin.vcs), and where the one or two
> parameters given to the program come from, to help such a developer who
> wants to add his own remote helper.

Junio: I think the first revision of my patch [1] is more along these
lines. I prepared this revision after Daniel Barkalow's comments [2]
and [3].
Daniel: Could you please comment on this?

-- Ram

[1] http://article.gmane.org/gmane.comp.version-control.git/143434
[2] http://thread.gmane.org/gmane.comp.version-control.git/143438
[3] http://thread.gmane.org/gmane.comp.version-control.git/143483

Re: [PATCH v4] Documentation/remote-helpers: Add invocation section

[Junio C Hamano]

Ramkumar Ramachandra <artagnon@gmail.com> writes:

> I prepared this revision after Daniel Barkalow's comments [2]
> and [3].
> Daniel: Could you please comment on this?

Sorry for putting you in an awkward place.  I think Daniel and I have
different target audience in mind for various pieces of documentation.

Here is what I think.

 - An end user who has heard of a "svn" foreign interface may want to look
   at something like urls.txt (which is included by the manual page for
   clone and perhaps fetch) to learn how to use a repository his friends
   who are still using Subversion use with his git installation.

   When "svn" foreign interface is polished enough to be a first class
   citizen, I would imagine that we would have a simple "to access
   Subversion repository using their native protocol, use the same URL as
   your Subversion friends use, e.g. svn://svn.rockbox.org/rockbox", and
   that description would appear at the same level as our native URLs like
   "git://k.org/pub/scm/git/git.git" (that is what I mean by "first class
   citizen").

 - On the other hand, I think git-remote-helpers.txt would be more for
   helper writers than the end users.  We could move detailed discussion
   that are needed by helper writers to Documentation/technical/, but then
   I do not see much else to discuss in git-remote-helpers left.  I do not
   see how the end user needs anything deeper than the simple "here is how
   you would give the protocol and location to your 'git clone' and
   everything else will be set up for you" that would be in urls.txt.

> [2] http://thread.gmane.org/gmane.comp.version-control.git/143438

  [regarding Ilari's description on how helper is chosen]

  That information ought to be in the documentation, but possibly not on 
  this man page in particular. I think it would be better to document that 
  part in the documentation of the code and programs that call the helper, 
  not in the helper documentation. In general, I'd like the helpers to make 
  as few assumptions about their caller as possible, and similarly keep the 
  information about the caller out of their documentation.

  Also, I think it would be more helpful in general to get that information 
  into documentation of the transport and remote code and configuration of 
  these things, because users are going to come at this from that side ("I 
  want to access an SVN repository, how does that work?") rather than from 
  the helper documentation side ("I want to exercise git-remote-svn's export 
  support, just to run that code").

While in principle I can understand Daniel's aversion of spelling things
out in too much detail to paint himself in a corner he cannot get out of,
I think it is necessary to give the overall picture to the readers (my
intended target audience is "helper writers").  In other words, I think
the documentation needs to say something like:

    "clone" gets transport and transport specific data to identify the
    data source in _this_ way from the user, stores it in .git/config for
    future interaction with the same foreign repository by _this_ and
    _that_ command, and all these will cause your helper program to be
    called _this_ way, hence your program must be prepared to do _this_
    and _that_.

and it wouldn't be as helpful to the helper writers if we only said the
last "your program must do this and that" part.

> [3] http://thread.gmane.org/gmane.comp.version-control.git/143483

  I think getting information on what the helper is supposed to do with its 
  command-line arguments into this man page would be good, and the 
  appropriate focus for the man page.

  The current answer is this:
   argv[1] is the name of a remote, which may be a nickname or some more 
    direct name; in any case, remote_get() will produce the available data 
    for it.
   argv[2] is the URL, if there is one. Since a remote could have more than 
    one URL, the helper gets the URL it should be handling. Some systems 
    don't use URLs, and these will just look at the remote or something like 
    that.

  The rest of what you wrote is true, but it's really more information on 
  how the attributes of remotes are determined than what the helper should 
  be worrying about.

Here mostly Daniel agrees with me that having techinical details that is
needed for helper writers in git-remote-helpers.txt is a good idea, but
I am not sure if I agree with the last paragraph.

Re: [PATCH v4] Documentation/remote-helpers: Add invocation section

[Ramkumar Ramachandra]

Hi,

On Tue, Apr 6, 2010 at 12:18 PM, Junio C Hamano <gitster@pobox.com> wrote:
> While in principle I can understand Daniel's aversion of spelling things
> out in too much detail to paint himself in a corner he cannot get out of,
> I think it is necessary to give the overall picture to the readers (my
> intended target audience is "helper writers").  In other words, I think
> the documentation needs to say something like:

Okay. I've tried my best to incorporate everything you've said into
v5. If there's some detail that will change later, the document can
always be updated :)

-- Ram

Re: [PATCH v4] Documentation/remote-helpers: Add invocation section

[Daniel Barkalow]

On Mon, 5 Apr 2010, Junio C Hamano wrote:

> I would think that INVOCATION section needs to specify how the helper is
> selected (e.g. taking "frotz" out of "frotz::<some info>", or using the
> configuration variable remote.origin.vcs), and where the one or two
> parameters given to the program come from, to help such a developer who
> wants to add his own remote helper.

I think where the helper gets selected should be described in the (more 
user-centric) documentation of how git uses external helpers; helper 
developers (who are writing their helper in the context of git) should 
generally be familiar with this from the user documentation. I'd like to 
keep this document as little specific to git being what calls the helper 
as possible.

	-Daniel
*This .sig left intentionally blank*