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

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Mar 11, 2015, 07:47 UTC
Message-ID: <CAPig+cTvX-yZpwC8BvN2CmgkBrOKUaotvJHdwXwfU8YnqLi4nQ@mail.gmail.com>
In-Reply-To: <1426056553-9364-4-git-send-email-pyokagan@gmail.com>

On Wed, Mar 11, 2015 at 2:49 AM, Paul Tan <pyokagan@gmail.com> wrote:

Show 34 quoted lines

> git-credential-store now supports an additional default credential file
> at $XDG_CONFIG_HOME/git/credentials. However, ~/.git-credentials takes
> precedence over it for backwards compatibility. To make the precedence
> ordering explicit, add a new section FILES that lists out the credential
> file paths in their order of precedence, and explains how the ordering
> affects the lookup, storage and erase operations.
>
> Also update documentation for --store to briefly explain the operations
> on multiple files if the --store option is not provided.
>
> Signed-off-by: Paul Tan <pyokagan@gmail.com>
> ---
> diff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt
> index bc97071..451c4fa 100644
> --- a/Documentation/git-credential-store.txt
> +++ b/Documentation/git-credential-store.txt
> @@ -31,10 +31,43 @@ OPTIONS
> +[[FILES]]
> +FILES
> +-----
> +
> +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.

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

Show 14 quoted lines

> +For credential lookups, the files are read in the order given above, with the
> +first matching credential found taking precedence over credentials found in
> +files further down the list.
> +
> +Credential storage will per default write to the first existing file in the
> +list. If none of these files exist, `~/.git-credentials` will be created and
> +written to.
> +
> +When erasing credentials, matching credentials will be erased from all files.
>
>  EXAMPLES
>  --------
> --
> 2.1.4