From 1bc1e940918cd44cc78bff1dfd518e16fc5bad57 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Mon, 25 Nov 2024 12:14:01 +0900 Subject: doc: option value may be separate for valid reasons Even though `git help cli` recommends users to prefer using "--option=value" over "--option value", there can be reasons why giving them separately is a good idea. One reason is that shells do not perform tilde expansion for `--option=~/path/name` but they expand `--options ~/path/name` just fine. This is not a problem for many options whose option parsing is properly written using OPT_FILENAME(), because the value given to OPT_FILENAME() is tilde-expanded internally by us, but some commands take a pathname as a mere string, which needs this trick to have the shell help us. I think the reason we originally decided to recommend the stuck form was because an option that takes an optional value requires you to use it in the stuck form, and it is one less thing for users to worry about if they get into the habit to always use the stuck form. But we should be discouraging ourselves from adding an option with an optional value in the first place, and we might want to weaken the current recommendation. In any case, let's describe this one case where it is necessary to use the separate form, with an example. Reviewed-by: Eric Sunshine Signed-off-by: Junio C Hamano --- Documentation/gitcredentials.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation/gitcredentials.txt') diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index 71dd19731a..35a7452c8f 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -242,6 +242,12 @@ Here are some example specifications: [credential] helper = "foo --bar='whitespace arg'" +# store helper (discouraged) with custom location for the db file; +# use `--file ~/.git-secret.txt`, rather than `--file=~/.git-secret.txt`, +# to allow the shell to expand tilde to the home directory. +[credential] + helper = "store --file ~/.git-secret.txt" + # you can also use an absolute path, which will not use the git wrapper [credential] helper = "/path/to/my/helper --with-arguments" -- cgit v1.3 From cf5b8276dcfdad44f02c082a934be5589ff14586 Mon Sep 17 00:00:00 2001 From: M Hickford Date: Fri, 10 Jan 2025 22:54:36 +0000 Subject: docs: list popular credential helpers git-credential-store saves credentials unencrypted on disk. It is the least secure choice of credential helper. Nevertheless, it appears several times more popular than any other credential helper [1]. Inform users about more secure alternatives. [1] https://stackoverflow.com/questions/35942754/how-can-i-save-username-and-password-in-git Signed-off-by: M Hickford Signed-off-by: Junio C Hamano --- Documentation/gitcredentials.txt | 41 ++++++++++++++++++++++++++++------------ 1 file changed, 29 insertions(+), 12 deletions(-) (limited to 'Documentation/gitcredentials.txt') diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index 35a7452c8f..3337bb475d 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -66,18 +66,7 @@ storage provided by the OS or other programs. Alternatively, a credential-generating helper might generate credentials for certain servers via some API. -To use a helper, you must first select one to use. Git currently -includes the following helpers: - -cache:: - - Cache credentials in memory for a short period of time. See - linkgit:git-credential-cache[1] for details. - -store:: - - Store credentials indefinitely on disk. See - linkgit:git-credential-store[1] for details. +To use a helper, you must first select one to use (see below for a list). You may also have third-party helpers installed; search for `credential-*` in the output of `git help -a`, and consult the @@ -106,6 +95,28 @@ $ git config --global credential.helper foo === Available helpers +Git currently includes the following helpers: + +cache:: + + Cache credentials in memory for a short period of time. See + linkgit:git-credential-cache[1] for details. + +store:: + + Store credentials indefinitely on disk. See + linkgit:git-credential-store[1] for details. + +Popular helpers with secure persistent storage include: + + - git-credential-libsecret (Linux) + + - git-credential-osxkeychain (macOS) + + - git-credential-wincred (Windows) + + - https://github.com/git-ecosystem/git-credential-manager[Git Credential Manager] (cross platform, included in Git for Windows) + The community maintains a comprehensive list of Git credential helpers at https://git-scm.com/doc/credential-helpers. @@ -116,6 +127,12 @@ OAuth credential helper. Initial authentication opens a browser window to the host. Subsequent authentication happens in the background. Many popular Git hosts support OAuth. +Popular helpers with OAuth support include: + + - https://github.com/git-ecosystem/git-credential-manager[Git Credential Manager] (cross platform, included in Git for Windows) + + - https://github.com/hickford/git-credential-oauth[git-credential-oauth] (cross platform, included in many Linux distributions) + CREDENTIAL CONTEXTS ------------------- -- cgit v1.3