Ramkumar Ramachandra <artagnon@xxxxxxxxx> 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@xxxxxxxxx> > --- > 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. -- 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