summaryrefslogtreecommitdiff
path: root/Documentation/gitcredentials.txt
AgeCommit message (Collapse)AuthorFilesLines
2020-08-04command-list.txt: add missing 'gitcredentials' and 'gitremote-helpers'Libravatar Philippe Blain1-1/+1
The guides 'gitcredentials' and 'gitremote-helpers' do not currently appear in command-list.txt. 'gitcredentials' was forgotten back when guides were added to command-list.txt in 1b81d8cb19 (help: use command-list.txt for the source of guides, 2018-05-20). 'gitremote-helpers' was moved to section 7 in 439cc74632 (docs: move gitremote-helpers into section 7, 2019-03-25), but command-list.txt was not updated at the time. Add these two guides to the list of guides in 'command-list.txt', so that they appear in the output of 'git help --guides', and capitalize the first word of the description of 'gitcredentials', as was done in 1b81d8c (help: use command-list.txt for the source of guides, 2018-05-20) for the other guides. While at it, add a comment in Documentation/Makefile to remind developers to update command-list.txt if they add a new guide. Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-05-13Merge branch 'cb/credential-doc-fixes'Libravatar Junio C Hamano1-8/+18
Minor in-code comments and documentation updates around credential API. * cb/credential-doc-fixes: credential: document protocol updates credential: update gitcredentials documentation credential: correct order of parameters for credential_match credential: update description for credential_from_url_gently
2020-05-07credential: update gitcredentials documentationLibravatar Carlo Marcelo Arenas Belón1-8/+18
Clarify the expected effect of all attributes and how the helpers are expected to handle them and the context where they operate. While at it, space the descriptions for clarity, and add a paragraph mentioning the early termination in the list processing of helpers, to complement the one about the special "quit" attribute. Signed-off-by: Carlo Marcelo Arenas Belón <carenas@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-05-01gitcredentials(7): make shell-snippet example more realisticLibravatar Jeff King1-2/+3
There's an example of using your own bit of shell to act as a credential helper, but it's not very realistic: - It's stupid to hand out your secret password to _every_ host. In the real world you'd use the config-matcher to limit it to a particular host. - We never provided a username. We can easily do that in another config option (you can do it in the helper, too, but this is much more readable). - We were sending the secret even for store/erase operations. This is OK because Git would just ignore it, but a real system would probably be unlocking a password store, which you wouldn't want to do more than necessary. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-05-01gitcredentials(7): clarify quoting of helper examplesLibravatar Jeff King1-5/+10
We give several helper config examples, but don't make clear that these are raw values. It's up to the user to add the appropriate quoting to put them into a config file (either by running with "git config" and quoting against the shell, or by adding double-quotes as appropriate within the git-config file). Let's flesh them out as full config blocks, which makes the syntax more clear (and makes it possible for people to just cut-and-paste them as a starting point). I added double-quotes to any values larger than a single word. That isn't strictly necessary in all cases, but it sidesteps explaining the rules about exactly when you need to quote a value. The existing quotes can be converted to single-quotes in one instance, and backslash-esccaped in the other. I also swapped out backticks for our preferred $(). Reported-by: douglas.fuller@gmail.com Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-03-05Merge branch 'bc/wildcard-credential'Libravatar Junio C Hamano1-1/+3
A configuration element used for credential subsystem can now use wildcard pattern to specify for which set of URLs the entry applies. * bc/wildcard-credential: credential: allow wildcard patterns when matching config credential: use the last matching username in the config t0300: add tests for some additional cases t1300: add test for urlmatch with multiple wildcards mailmap: add an additional email address for brian m. carlson
2020-02-20credential: allow wildcard patterns when matching configLibravatar brian m. carlson1-1/+3
In some cases, a user will want to use a specific credential helper for a wildcard pattern, such as https://*.corp.example.com. We have code that handles this already with the urlmatch code, so let's use that instead of our custom code. Since the urlmatch code is a superset of our current matching in terms of capabilities, there shouldn't be any cases of things that matched previously that don't match now. However, in addition to wildcard matching, we now use partial path matching, which can cause slightly different behavior in the case that a helper applies to the prefix (considering path components) of the remote URL. While different, this is probably the behavior people were wanting anyway. Since we're using the urlmatch code, we need to encode the components we've gotten into a URL to match, so add a function to percent-encode data and format the URL with it. We now also no longer need to the custom code to match URLs, so let's remove it. Additionally, the urlmatch code always looks for the best match, whereas we want all matches for credential helpers to preserve existing behavior. Let's add an optional field, select_fn, that lets us control which items we want (in this case, all of them) and default it to the best-match code that already exists for other users. Signed-off-by: brian m. carlson <bk2204@github.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-02-14doc: move credential helper info into gitcredentials(7)Libravatar Jeff King1-1/+88
The details of how credential helpers can be called or implemented were originally covered in Documentation/technical/. Those are topics that end users might care about (and we even referenced them in the credentials manpage), but those docs typically don't ship as part of the end user documentation, making them less useful. This situation got slightly worse recently in f3b9055624 (credential: move doc to credential.h, 2019-11-17), where we moved them into the C header file, making them even harder to find. So let's move put this information into the gitcredentials(7) documentation, which is meant to describe the overall concepts of our credential handling. This was already pointing to the API docs for these concepts, so we can just include it inline instead. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-11-18credential: move doc to credential.hLibravatar Heba Waly1-2/+1
Move the documentation from Documentation/technical/api-credentials.txt to credential.h as it's easier for the developers to find the usage information beside the code instead of looking for it in another doc file. Documentation/technical/api-credentials.txt is removed because the information it has is now redundant and it'll be hard to keep it up to date and synchronized with the documentation in the header file. Documentation/git-credential.txt and Documentation/gitcredentials.txt now link to credential.h instead of Documentation/technical/api-credentials.txt for details about the credetials API. Signed-off-by: Heba Waly <heba.waly@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-09-27doc: clarify gitcredentials path component matchingLibravatar David Zych1-0/+6
The gitcredentials documentation implied that the config file's "pattern" URL might include a path component, but did not explain that it must match exactly (potentially leaving readers with the false hope that it would support a more flexible prefix match). Signed-off-by: David Zych <dmrz@illinois.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-05-02credential doc: make multiple-helper behavior more prominentLibravatar Jonathan Nieder1-10/+10
Git's configuration system works by reading multiple configuration files in order, from general to specific: - first, the system configuration /etc/gitconfig - then the user's configuration (~/.gitconfig or ~/.config/git/config) - then the repository configuration (.git/config) For single-valued configuration items, the latest value wins. For multi-valued configuration items, values accumulate in that order. For example, this allows setting a credential helper globally in ~/.gitconfig that git will try to use in all repositories, regardless of whether they additionally provide another helper. This is usually a nice thing --- e.g. I can install helpers to use my OS keychain and to cache credentials for a short period of time globally. Sometimes people want to be able to override an inherited setting. For the credential.helper setting, this is done by setting the configuration item to empty before giving it a new value. This is already documented but the documentation is hard to find --- git-config(1) says to look at gitcredentials(7) and the config reference in gitcredentials(7) doesn't mention this issue. Move the documentation to the config reference to make it easier to find. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-02-26credential: let empty credential specs reset helper listLibravatar Jeff King1-0/+5
Sine the credential.helper key is a multi-valued config list, there's no way to "unset" a helper once it's been set. So if your system /etc/gitconfig sets one, you can never avoid running it, but only add your own helpers on top. Since an empty value for credential.helper is nonsensical (it would just try to run "git-credential-"), we can assume nobody is using it. Let's define it to reset the helper list, letting you override lower-priority instances which have come before. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-03-13*config.txt: stick to camelCase naming conventionLibravatar Nguyễn Thái Ngọc Duy1-1/+1
This should improve readability. Compare "thislongname" and "thisLongName". The following keys are left in unchanged. We can decide what to do with them later. - am.keepcr - core.autocrlf .safecrlf .trustctime - diff.dirstat .noprefix - gitcvs.usecrlfattr - gui.blamehistoryctx .trustmtime - pull.twohead - receive.autogc - sendemail.signedoffbycc .smtpsslcertpath .suppresscc Helped-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-01Documentation: the name of the system is 'Git', not 'git'Libravatar Thomas Ackermann1-12/+12
Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-04-26docs: stop using asciidoc no-inline-literalLibravatar Jeff King1-2/+2
In asciidoc 7, backticks like `foo` produced a typographic effect, but did not otherwise affect the syntax. In asciidoc 8, backticks introduce an "inline literal" inside which markup is not interpreted. To keep compatibility with existing documents, asciidoc 8 has a "no-inline-literal" attribute to keep the old behavior. We enabled this so that the documentation could be built on either version. It has been several years now, and asciidoc 7 is no longer in wide use. We can now decide whether or not we want inline literals on their own merits, which are: 1. The source is much easier to read when the literal contains punctuation. You can use `master~1` instead of `master{tilde}1`. 2. They are less error-prone. Because of point (1), we tend to make mistakes and forget the extra layer of quoting. This patch removes the no-inline-literal attribute from the Makefile and converts every use of backticks in the documentation to an inline literal (they must be cleaned up, or the example above would literally show "{tilde}" in the output). Problematic sites were found by grepping for '`.*[{\\]' and examined and fixed manually. The results were then verified by comparing the output of "html2text" on the set of generated html pages. Doing so revealed that in addition to making the source more readable, this patch fixes several formatting bugs: - HTML rendering used the ellipsis character instead of literal "..." in code examples (like "git log A...B") - some code examples used the right-arrow character instead of '->' because they failed to quote - api-config.txt did not quote tilde, and the resulting HTML contained a bogus snippet like: <tt><sub></tt> foo <tt></sub>bar</tt> which caused some parsers to choke and omit whole sections of the page. - git-commit.txt confused ``foo`` (backticks inside a literal) with ``foo'' (matched double-quotes) - mentions of `A U Thor <author@example.com>` used to erroneously auto-generate a mailto footnote for author@example.com - the description of --word-diff=plain incorrectly showed the output as "[-removed-] and {added}", not "{+added+}". - using "prime" notation like: commit `C` and its replacement `C'` confused asciidoc into thinking that everything between the first backtick and the final apostrophe were meant to be inside matched quotes - asciidoc got confused by the escaping of some of our asterisks. In particular, `credential.\*` and `credential.<url>.\*` properly escaped the asterisk in the first case, but literally passed through the backslash in the second case. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-12-12credentials: add "store" helperLibravatar Jeff King1-0/+5
This is like "cache", except that we actually put the credentials on disk. This can be terribly insecure, of course, but we do what we can to protect them by filesystem permissions, and we warn the user in the documentation. This is not unlike using .netrc to store entries, but it's a little more user-friendly. Instead of putting credentials in place ahead of time, we transparently store them after prompting the user for them once. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-12-11credentials: add "cache" helperLibravatar Jeff King1-5/+12
If you access repositories over smart-http using http authentication, then it can be annoying to have git ask you for your password repeatedly. We cache credentials in memory, of course, but git is composed of many small programs. Having to input your password for each one can be frustrating. This patch introduces a credential helper that will cache passwords in memory for a short period of time. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-12-11docs: end-user documentation for the credential subsystemLibravatar Jeff King1-0/+171
The credential API and helper format is already defined in technical/api-credentials.txt. This presents the end-user view. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>