Re: [PATCH 1/2] git-svn: add some in-code documentation (options-related).

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 21, 2009, 23:48 UTC
Message-ID: <7vmy81p2r5.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1245624521-30769-2-git-send-email-ydirson@altern.org>

Yann Dirson <ydirson@altern.org> writes:

Show 5 quoted lines

> +# Option structures here are used to define both command-line options
> +# and git-config keys.  They are handled by read-repo-config().
> +# Options in mixed case and with only a long form are only for the
> +# config file.  All options available from command-line are available
> +# as config-file options too, but without any dash in their names.

Hmm... I am a bit confused.  So for example:

		'authors-file|A=s' => \$_authors,
		'authors-prog=s' => \$_authors_prog,
		'repack:i' => \$Git::SVN::_repack,
		'noMetadata' => \$Git::SVN::_no_metadata,
		'useSvmProps' => \$Git::SVN::_use_svm_props,

authors-file, authors-prog and repack are not MixdCase (and the first and third are not even "only a long form"), so it is not "only for the config file". But noMetadata and useSvmProps are "only for the config file".

It took me a bit to realize that these two equivalence hold:

  "not only for the config file" === "also available as command line option"
  "only for the config file"     === "cannot be given on the command line"

Since "option structures here are used for both command and config", and "anything usable from command line can be used in config file", logically it follows that "everything in these option structures here are usable in the config". It took me a bit longer than necessary for that to click, too.

Perhaps I am slow.  But I suspect I am not the slowest around here.

After scratching my head for a few minutes, here is a rephrased description I came up with (I am not writing this as an improved suggestion, but to ask you to sanity check if I read what you wanted to say correctly):

    These are all configurable in the config file (remove dash in their
    names to use these names as the config key).

    Options that have MixedCase names without short format (e.g. noMetadata)
    can only be used from the configuration (iow they cannot be given from
    the command line as options).

But then this raises a couple of questions.

 * What are the examples of MixedCase names that do have short format?
   Are they usable from the command line?

 * %fc_opts() has "noMetadata" and %init_opts() has "no-metadata"; how are
   they related, and how do they affect the above "what's available where
   and how to spell their names" rule you outlined?