Inconsistency in git credential helper docs

Inconsistency in git credential helper docs

[Chris Chow]

Hello,

There appears to be a small inconsistency / bug in the documentation
located at https://git-scm.com/docs/gitcredentials.

Under the "Custom Helpers" subhead, there's a line that reads
> Generally speaking, rule (3) above is the simplest for users to specify. Authors of credential helpers should make an effort to assist their users by naming their program "git-credential-$NAME", and putting it in the $PATH or $GIT_EXEC_PATH during installation, which will allow a user to enable it with git config credential.helper $NAME.

Earlier in the document, under "Configuration Options > helper", there
is a line that reads
> The name of an external credential helper, and any associated options. If the helper name is not an absolute path, then the string git credential- is prepended

I think the latter text is correct. The maintainers of the google
cloud SDK followed the advice in the first part, naming their cred
helper `git-credential-gcloud.sh`, which is not accessible if you set
the custom credential helper to `gcloud.sh`. I had to make a symlink
at `credential-gcloud.sh`, following the instructions in the latter
block, to make it work. One could of course just specify the full path
in .gitconfig, but I figured it might be good to have these parts be
consistent anyways.

Best,
Chris

Re: Inconsistency in git credential helper docs

[Jeff King]

On Mon, Oct 11, 2021 at 02:36:13PM -0700, Chris Chow wrote:

> There appears to be a small inconsistency / bug in the documentation
> located at https://git-scm.com/docs/gitcredentials.

I'm not sure I see what you mean.

> Under the "Custom Helpers" subhead, there's a line that reads
> > Generally speaking, rule (3) above is the simplest for users to specify. Authors of credential helpers should make an effort to assist their users by naming their program "git-credential-$NAME", and putting it in the $PATH or $GIT_EXEC_PATH during installation, which will allow a user to enable it with git config credential.helper $NAME.

OK, so here you'd call your helper git-credential-gcloud.sh so that:

  git config credential.helper gcloud.sh

would work.

> Earlier in the document, under "Configuration Options > helper", there
> is a line that reads
> > The name of an external credential helper, and any associated options. If the helper name is not an absolute path, then the string git credential- is prepended

And likewise here, we will run "git credential-gcloud.sh", which in turn
calls "git-credential-gcloud.sh" (since there is no builtin of that
name).

But we would never call "credential-gcloud.sh" in this way. You
could say:

  git config credential.helper '!credential-gcloud.sh'

of course, but that is skipping the auto-name stuff entirely.

> I think the latter text is correct. The maintainers of the google
> cloud SDK followed the advice in the first part, naming their cred
> helper `git-credential-gcloud.sh`, which is not accessible if you set
> the custom credential helper to `gcloud.sh`. I had to make a symlink
> at `credential-gcloud.sh`, following the instructions in the latter
> block, to make it work. One could of course just specify the full path
> in .gitconfig, but I figured it might be good to have these parts be
> consistent anyways.

Both pieces of text are pointing to the name that the gcloud folks used.
I'm not sure why it didn't work, or how a symlink could possibly have
helped. Can you share the exact sequence of commands, with output, that
shows what you're seeing?

Here's a toy example that shows the kind of thing that should work:

  # toy helper that lets us know when it's running
  { echo '#!/bin/sh' && echo 'echo >&2 running the foo helper'; } >foo.sh
  chmod +x foo.sh

  # add our current directory to PATH to experiment; usually these
  # commands would go into /usr/local/bin, ~/bin, etc
  export PATH=$PATH:$PWD

  # make sure we're in a repo so we can stick our config somewhere. In
  # the real world you'd probably be using "git config --global" or
  # similar.
  git init
  git config credential.helper foo.sh

  # this should say "credential-foo.sh is not a git command", because we
  # tried to run "git credential-foo.sh", but that doesn't exist (the
  # command itself is a noop; it just tries to remove a bogus credential
  # that you don't actually have, but that's enough to trigger each
  # helper).
  echo url=https://user:pass@example.com | git credential reject

  # now try it again with credential-foo.sh in the path. That also won't
  # work, with the same outcome.
  mv foo.sh credential-foo.sh
  echo url=https://user:pass@example.com | git credential reject

  # now try it with git-credential-foo.sh in the path. This should
  # trigger the helper successfully.
  mv credential-foo.sh git-credential-foo.sh
  echo url=https://user:pass@example.com | git credential reject

What I'm suspecting is that the "credential-foo.sh is not a git command"
message may have confused you, and then while debugging it you did
something else (e.g., tweaking your PATH, setting the execute bit, etc)
that led the original git-credential-gcloud.sh to work.

-Peff