On Mon, 29 Mar 2010, Ramkumar Ramachandra wrote:
> Hi,
>
> > 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.
>
> I agree that the callers need to document the subset of the
> invocations they make to remote helpers. I think we can defer this
> until we have a real remote helper in `git.git` that actually
> interfaces with a foreign versioning system.
>
> I've thought about documenting the full set of invocations in the code
> for the developer, but there's a problem. Here's an excerpt from
> remote-curl.c, showing how it parses its command line arguments:
>
> remote = remote_get(argv[1]);
>
> if (argc > 2) {
> url = argv[2];
> } else {
> url = remote->url[0];
> }
>
> Unfortunately, I don't see where else this documentation can fit in:
> if it were to go into a specific remote helper's code, then it'll have
> to be duplicated for all the remote helpers, since all of them parse
> options similarly. It certainly cannot go into remote.c or
> transport-helper.c, because they have little/ nothing to do with the
> actual argument parsing.
>
> I could try modifying the documentation I've written to serve more to
> specify "how remote helpers are invoked" and less about "how callers
> invoke remote helpers", and try to fit it in this manpage. It's more
> of a developer manpage and less of an end-user manpage as it is. Or we
> could create another page about remote helpers intended to be read
> exclusively by developers. What are your thoughts on this?
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.
-Daniel
*This .sig left intentionally blank*
--
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