On 18.11.2021 17:14, Eric Sunshine wrote:
On Thu, Nov 18, 2021 at 12:14 PM Fabian Stelzer <fs@xxxxxxxxxxxx> wrote:
The user.signingKey config for ssh signing supports either a path to a
file containing the key or for the sake of convenience a literal string
with the ssh public key. To differentiate between those two cases we
check if the first few characters contain "ssh-" which is unlikely to be
the start of a path. ssh supports other key types which are not prefixed
with "ssh-" and will currently be treated as a file path and therefore
fail to load. To remedy this we move the prefix check into its own
function and introduce the prefix `key::` for literal ssh keys. This way
we don't need to add new key types when they become available. The
existing `ssh-` prefix is retained for compatibility with current user
configs but removed from the official documentation to discourage its
use.
I think we usually avoid removing documentation for something which is
still supported (even if deprecated) for the very real reason that
people will still encounter the old form in the wild, whether in
configuration files, in blogs, or elsewhere, and may be perplexed to
discover that the form is not documented (thus not understand how or
why it seems to be working). Instead, we can discourage its use by
mentioning clearly that it is deprecated and that `key::` should be
used instead.
I thought since this only existed in the docs since the 2.34
release a few days ago i could get away with it ;)
But since we keep the support for `ssh-` in the code we should document
it as such. I'll add your suggestion below to it.
Thanks for your help.
Signed-off-by: Fabian Stelzer <fs@xxxxxxxxxxxx>
---
diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt
@@ -36,10 +36,10 @@ user.signingKey::
This option is passed unchanged to gpg's --local-user parameter,
so you may specify a key using any method that gpg supports.
- If gpg.format is set to "ssh" this can contain the literal ssh public
- key (e.g.: "ssh-rsa XXXXXX identifier") or a file which contains it and
- corresponds to the private key used for signing. The private key
- needs to be available via ssh-agent. Alternatively it can be set to
- a file containing a private key directly. If not set git will call
- gpg.ssh.defaultKeyCommand (e.g.: "ssh-add -L") and try to use the first
- key available.
+ If gpg.format is set to `ssh` this can contain the path to either
+ your private ssh key or the public key when ssh-agent is used.
+ Alternatively it can contain a public key prefixed with `key::`
+ directly (e.g.: "key::ssh-rsa XXXXXX identifier"). The private key
+ needs to be available via ssh-agent. If not set git will call
+ gpg.ssh.defaultKeyCommand (e.g.: "ssh-add -L") and try to use the
+ first key available.
Thus, perhaps this text could end with:
For backward compatibility, a raw key which begins with "ssh-",
such as "ssh-rsa XXXXXX identifier", is treated as "key::ssh-rsa
XXXXXX identifier", but this form is deprecated; use the `key::`
form instead.
