Re: [PATCH v3 3/4] docs/git-credential-store: document XDG file and precedence

On Wed, Mar 11, 2015 at 3:47 PM, Eric Sunshine [off-list ref] wrote:

On Wed, Mar 11, 2015 at 2:49 AM, Paul Tan [off-list ref] wrote:

quoted

+
+If not set explicitly with '--file', there are two files where
+git-credential-store will search for credentials in order of precedence:
+
+~/.git-credentials::
+       User-specific credentials file.
+
+$XDG_CONFIG_HOME/git/credentials::
+       Second user-specific credentials file. If '$XDG_CONFIG_HOME' is not set
+       or empty, `$HOME/.config/git/credentials` will be used. Any credentials
+       stored in this file will not be used if `~/.git-credentials` has a
+       matching credential as well. It is a good idea not to create this file
+       if you sometimes use older versions of Git, as support for this file
+       was added fairly recently.

The final sentence won't age well: "fairly recently" is too nebulous.
It may be sufficient merely to advise the reader to avoid this file if
she also uses an older version of Git which doesn't support XDG for
credentials.

I copied this part from the documentation of git-config. I couldn't
find the exact patch in the archives where "fairly recently" was
introduced, but I did find this patch[1] where apparently a version
number was supposed to be used instead.

[1] http://thread.gmane.org/gmane.comp.version-control.git/198837/focus=200552

So yes, at this point in time I think the sentence should be changed
to something like "It is a good idea not to create this file if you
use older versions of git that do not support this file.", although it
would be even more useful for users if the version where this feature
was introduced is stated as well. This patch series has not even hit
pu though ;)

Other than this minor point, the patch series seems well prepared and
quite nicely done. Thanks.

Thank you so much for the positive review. Will re-roll the documentation.

Regards,
Paul