From: "Carlo Marcelo Arenas Belón" <carenas@gmail.com>
To: git@vger.kernel.org
Cc: peff@peff.net, jrnieder@gmail.com,
"Carlo Marcelo Arenas Belón" <carenas@gmail.com>
Subject: [PATCH v2 4/4] credential: document protocol updates
Date: Wed, 6 May 2020 14:47:26 -0700 [thread overview]
Message-ID: <20200506214726.81854-5-carenas@gmail.com> (raw)
In-Reply-To: <20200506214726.81854-1-carenas@gmail.com>
Document protocol changes after CVE-2020-11008, including the removal of
references to the override of attributes which is no longer recommended
after CVE-2020-5260 and that might be removed in the future.
While at it do some improvements for clarity and consistency.
Signed-off-by: Carlo Marcelo Arenas Belón <carenas@gmail.com>
---
Documentation/git-credential.txt | 34 ++++++++++++++++++++------------
1 file changed, 21 insertions(+), 13 deletions(-)
diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt
index 6f0c7ca80f..8d990e92fd 100644
--- a/Documentation/git-credential.txt
+++ b/Documentation/git-credential.txt
@@ -103,17 +103,20 @@ INPUT/OUTPUT FORMAT
`git credential` reads and/or writes (depending on the action used)
credential information in its standard input/output. This information
can correspond either to keys for which `git credential` will obtain
-the login/password information (e.g. host, protocol, path), or to the
-actual credential data to be obtained (login/password).
+the login information (e.g. host, protocol, path), or to the actual
+credential data to be obtained (username/password).
The credential is split into a set of named attributes, with one
-attribute per line. Each attribute is
-specified by a key-value pair, separated by an `=` (equals) sign,
-followed by a newline. The key may contain any bytes except `=`,
-newline, or NUL. The value may contain any bytes except newline or NUL.
+attribute per line. Each attribute is specified by a key-value pair,
+separated by an `=` (equals) sign, followed by a newline.
+
+The key may contain any bytes except `=`, newline, or NUL. The value may
+contain any bytes except newline or NUL.
+
In both cases, all bytes are treated as-is (i.e., there is no quoting,
and one cannot transmit a value with newline or NUL in it). The list of
attributes is terminated by a blank line or end-of-file.
+
Git understands the following attributes:
`protocol`::
@@ -123,7 +126,8 @@ Git understands the following attributes:
`host`::
- The remote hostname for a network credential.
+ The remote hostname for a network credential. This includes
+ the port number if one was specified (e.g., "example.com:8088").
`path`::
@@ -134,7 +138,7 @@ Git understands the following attributes:
`username`::
The credential's username, if we already have one (e.g., from a
- URL, from the user, or from a previously run helper).
+ URL, the configuration, the user, or from a previously run helper).
`password`::
@@ -146,8 +150,12 @@ Git understands the following attributes:
value is parsed as a URL and treated as if its constituent parts
were read (e.g., `url=https://example.com` would behave as if
`protocol=https` and `host=example.com` had been provided). This
- can help callers avoid parsing URLs themselves. Note that any
- components which are missing from the URL (e.g., there is no
- username in the example above) will be set to empty; if you want
- to provide a URL and override some attributes, provide the URL
- attribute first, followed by any overrides.
+ can help callers avoid parsing URLs themselves.
+
+ Note that specifying a protocol is mandatory and if the URL
+ doesn't specify a hostname (e.g., "cert:///path/to/file") the
+ credential will contain a hostname attribute whose value is an
+ empty string.
+
+ Components which are missing from the URL (e.g., there is no
+ username in the example above) will be left unset.
--
2.26.2.686.gfaf46a9ccd
next prev parent reply other threads:[~2020-05-06 21:48 UTC|newest]
Thread overview: 29+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-05-03 6:34 [RFC PATCH] credential: minor documentation fixes Carlo Marcelo Arenas Belón
2020-05-03 6:58 ` Jeff King
2020-05-04 7:45 ` Carlo Marcelo Arenas Belón
2020-05-04 14:44 ` Jeff King
2020-05-04 15:39 ` Carlo Marcelo Arenas Belón
2020-05-04 16:10 ` Jeff King
2020-05-04 15:58 ` Carlo Marcelo Arenas Belón
2020-05-04 16:13 ` Jeff King
2020-05-05 1:39 ` [PATCH 0/4] credential: documentation updates for maint Carlo Marcelo Arenas Belón
2020-05-05 1:39 ` [PATCH 1/4] credential: update description for credential_from_url_gently Carlo Marcelo Arenas Belón
2020-05-05 1:39 ` [PATCH 2/4] credential: correct order of parameters for credential_match Carlo Marcelo Arenas Belón
2020-05-05 1:39 ` [PATCH 3/4] credential: update gitcredentials documentation Carlo Marcelo Arenas Belón
2020-05-06 16:21 ` Jeff King
2020-05-05 1:39 ` [PATCH 4/4] credential: document protocol updates Carlo Marcelo Arenas Belón
2020-05-06 16:26 ` Jeff King
2020-05-06 16:27 ` [PATCH 0/4] credential: documentation updates for maint Jeff King
2020-05-06 23:28 ` Carlo Marcelo Arenas Belón
2020-05-07 20:59 ` Jeff King
2020-05-07 21:23 ` Carlo Marcelo Arenas Belón
2020-05-07 22:17 ` Jeff King
2020-05-07 23:35 ` Carlo Marcelo Arenas Belón
2020-05-06 21:47 ` [PATCH v2 " Carlo Marcelo Arenas Belón
2020-05-06 21:47 ` [PATCH v2 1/4] credential: update description for credential_from_url_gently Carlo Marcelo Arenas Belón
2020-05-06 21:47 ` [PATCH v2 2/4] credential: correct order of parameters for credential_match Carlo Marcelo Arenas Belón
2020-05-06 21:47 ` [PATCH v2 3/4] credential: update gitcredentials documentation Carlo Marcelo Arenas Belón
2020-05-07 20:54 ` Jeff King
2020-05-07 21:02 ` Junio C Hamano
2020-05-06 21:47 ` Carlo Marcelo Arenas Belón [this message]
2020-05-07 20:57 ` [PATCH v2 4/4] credential: document protocol updates Jeff King
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200506214726.81854-5-carenas@gmail.com \
--to=carenas@gmail.com \
--cc=git@vger.kernel.org \
--cc=jrnieder@gmail.com \
--cc=peff@peff.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).