technical/api-credentials.html - external/gitster/git-htmldocs - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
  "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
 <meta name="generator" content="AsciiDoc 8.5.2" />
 <title>credentials API</title>
 <style type="text/css">
 /* Debug borders */
 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
 /*
  border: 1px solid red;
 */
 }

 body {
  margin: 1em 5% 1em 5%;
 }

 a {
  color: blue;
  text-decoration: underline;
 }
 a:visited {
  color: fuchsia;
 }

 em {
  font-style: italic;
  color: navy;
 }

 strong {
  font-weight: bold;
  color: #083194;
 }

 tt {
  color: navy;
 }

 h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  font-family: sans-serif;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
 }

 h1, h2, h3 {
  border-bottom: 2px solid silver;
 }
 h2 {
  padding-top: 0.5em;
 }
 h3 {
  float: left;
 }
 h3 + * {
  clear: left;
 }

 div.sectionbody {
  font-family: serif;
  margin-left: 0;
 }

 hr {
  border: 1px solid silver;
 }

 p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
 }

 ul, ol, li > p {
  margin-top: 0;
 }

 pre {
  padding: 0;
  margin: 0;
 }

 span#author {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  font-size: 1.1em;
 }
 span#email {
 }
 span#revnumber, span#revdate, span#revremark {
  font-family: sans-serif;
 }

 div#footer {
  font-family: sans-serif;
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
 }
 div#footer-text {
  float: left;
  padding-bottom: 0.5em;
 }
 div#footer-badges {
  float: right;
  padding-bottom: 0.5em;
 }

 div#preamble {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
 }
 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 div.admonitionblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
 }
 div.admonitionblock {
  margin-top: 2.0em;
  margin-bottom: 2.0em;
  margin-right: 10%;
  color: #606060;
 }

 div.content { /* Block element content. */
  padding: 0;
 }

 /* Block element titles. */
 div.title, caption.title {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
 }
 div.title + * {
  margin-top: 0;
 }

 td div.title:first-child {
  margin-top: 0.0em;
 }
 div.content div.title:first-child {
  margin-top: 0.0em;
 }
 div.content + div.title {
  margin-top: 0.0em;
 }

 div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
 }

 div.listingblock > div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
 }

 div.quoteblock, div.verseblock {
  padding-left: 1.0em;
  margin-left: 1.0em;
  margin-right: 10%;
  border-left: 5px solid #dddddd;
  color: #777777;
 }

 div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
 }

 div.verseblock > div.content {
  white-space: pre;
 }
 div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
 }
 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
 div.verseblock + div.attribution {
  text-align: left;
 }

 div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
 }
 div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 3px solid #dddddd;
 }

 div.exampleblock > div.content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
 }

 div.imageblock div.content { padding-left: 0; }
 span.image img { border-style: none; }
 a.image:visited { color: white; }

 dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
 }
 dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: navy;
 }
 dd > *:first-child {
  margin-top: 0.1em;
 }

 ul, ol {
  list-style-position: outside;
 }
 ol.arabic {
  list-style-type: decimal;
 }
 ol.loweralpha {
  list-style-type: lower-alpha;
 }
 ol.upperalpha {
  list-style-type: upper-alpha;
 }
 ol.lowerroman {
  list-style-type: lower-roman;
 }
 ol.upperroman {
  list-style-type: upper-roman;
 }

 div.compact ul, div.compact ol,
 div.compact p, div.compact p,
 div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
 }

 div.tableblock > table {
  border: 3px solid #527bbd;
 }
 thead, p.table.header {
  font-family: sans-serif;
  font-weight: bold;
 }
 tfoot {
  font-weight: bold;
 }
 td > div.verse {
  white-space: pre;
 }
 p.table {
  margin-top: 0;
 }
 /* Because the table frame attribute is overriden by CSS in most browsers. */
 div.tableblock > table[frame="void"] {
  border-style: none;
 }
 div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
 }
 div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
 }


 div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
 }
 div.hdlist tr {
  padding-bottom: 15px;
 }
 dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
 }
 td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: navy;
 }
 td.hdlist2 {
  vertical-align: top;
 }
 div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
 }

 .comment {
  background: yellow;
 }

 .footnote, .footnoteref {
  font-size: 0.8em;
 }

 span.footnote, span.footnoteref {
  vertical-align: super;
 }

 #footnotes {
  margin: 20px 0 20px 0;
  padding: 7px 0 0 0;
 }

 #footnotes div.footnote {
  margin: 0 0 5px 0;
 }

 #footnotes hr {
  border: none;
  border-top: 1px solid silver;
  height: 1px;
  text-align: left;
  margin-left: 0;
  width: 20%;
  min-width: 100px;
 }


 @media print {
  div#footer-badges { display: none; }
 }

 div#toc {
  margin-bottom: 2.5em;
 }

 div#toctitle {
  color: #527bbd;
  font-family: sans-serif;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
 }

 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
 }
 div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
 }
 div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
 }
 div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
 }
 /* Workarounds for IE6's broken and incomplete CSS2. */

 div.sidebar-content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
 }
 div.sidebar-title, div.image-title {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  margin-top: 0.0em;
  margin-bottom: 0.5em;
 }

 div.listingblock div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
 }

 div.quoteblock-attribution {
  padding-top: 0.5em;
  text-align: right;
 }

 div.verseblock-content {
  white-space: pre;
 }
 div.verseblock-attribution {
  padding-top: 0.75em;
  text-align: left;
 }

 div.exampleblock-content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
 }

 /* IE6 sets dynamically generated links as visited. */
 div#toc a:visited { color: blue; }
 </style>
 <script type="text/javascript">
 /*<![CDATA[*/
 window.onload = function(){asciidoc.footnotes();}
 var asciidoc = { // Namespace.

 /////////////////////////////////////////////////////////////////////
 // Table Of Contents generator
 /////////////////////////////////////////////////////////////////////

 /* Author: Mihai Bazon, September 2002
  * http://students.infoiasi.ro/~mishoo
  *
  * Table Of Content generator
  * Version: 0.4
  *
  * Feel free to use this script under the terms of the GNU General Public
  * License, as long as you do not remove or alter this notice.
  */

  /* modified by Troy D. Hanson, September 2006. License: GPL */
  /* modified by Stuart Rackham, 2006, 2009. License: GPL */

 // toclevels = 1..4.
 toc: function (toclevels) {

  function getText(el) {
  var text = "";
  for (var i = el.firstChild; i != null; i = i.nextSibling) {
  if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
  text += i.data;
  else if (i.firstChild != null)
  text += getText(i);
  }
  return text;
  }

  function TocEntry(el, text, toclevel) {
  this.element = el;
  this.text = text;
  this.toclevel = toclevel;
  }

  function tocEntries(el, toclevels) {
  var result = new Array;
  var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
  // Function that scans the DOM tree for header elements (the DOM2
  // nodeIterator API would be a better technique but not supported by all
  // browsers).
  var iterate = function (el) {
  for (var i = el.firstChild; i != null; i = i.nextSibling) {
  if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
  var mo = re.exec(i.tagName);
  if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
  result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
  }
  iterate(i);
  }
  }
  }
  iterate(el);
  return result;
  }

  var toc = document.getElementById("toc");
  var entries = tocEntries(document.getElementById("content"), toclevels);
  for (var i = 0; i < entries.length; ++i) {
  var entry = entries[i];
  if (entry.element.id == "")
  entry.element.id = "_toc_" + i;
  var a = document.createElement("a");
  a.href = "#" + entry.element.id;
  a.appendChild(document.createTextNode(entry.text));
  var div = document.createElement("div");
  div.appendChild(a);
  div.className = "toclevel" + entry.toclevel;
  toc.appendChild(div);
  }
  if (entries.length == 0)
  toc.parentNode.removeChild(toc);
 },


 /////////////////////////////////////////////////////////////////////
 // Footnotes generator
 /////////////////////////////////////////////////////////////////////

 /* Based on footnote generation code from:
  * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
  */

 footnotes: function () {
  var cont = document.getElementById("content");
  var noteholder = document.getElementById("footnotes");
  var spans = cont.getElementsByTagName("span");
  var refs = {};
  var n = 0;
  for (i=0; i<spans.length; i++) {
  if (spans[i].className == "footnote") {
  n++;
  // Use [\s\S] in place of . so multi-line matches work.
  // Because JavaScript has no s (dotall) regex flag.
  note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
  noteholder.innerHTML +=
  "<div class='footnote' id='_footnote_" + n + "'>" +
  "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
  n + "</a>. " + note + "</div>";
  spans[i].innerHTML =
  "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
  "' title='View footnote' class='footnote'>" + n + "</a>]";
  var id =spans[i].getAttribute("id");
  if (id != null) refs["#"+id] = n;
  }
  }
  if (n == 0)
  noteholder.parentNode.removeChild(noteholder);
  else {
  // Process footnoterefs.
  for (i=0; i<spans.length; i++) {
  if (spans[i].className == "footnoteref") {
  var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
  href = href.match(/#.*/)[0]; // Because IE return full URL.
  n = refs[href];
  spans[i].innerHTML =
  "[<a href='#_footnote_" + n +
  "' title='View footnote' class='footnote'>" + n + "</a>]";
  }
  }
  }
 }

 }
 /*]]>*/
 </script>
 </head>
 <body>
 <div id="header">
 <h1>credentials API</h1>
 </div>
 <div id="content">
 <div id="preamble">
 <div class="sectionbody">
 <div class="paragraph"><p>The credentials API provides an abstracted way of gathering username and
 password credentials from the user (even though credentials in the wider
 world can take many forms, in this document the word "credential" always
 refers to a username and password pair).</p></div>
 </div>
 </div>
 <h2 id="_data_structures">Data Structures</h2>
 <div class="sectionbody">
 <div class="dlist"><dl>
 <dt class="hdlist1">
 <tt>struct credential</tt>
 </dt>
 <dd>
 <p>
  This struct represents a single username/password combination
  along with any associated context. All string fields should be
  heap-allocated (or NULL if they are not known or not applicable).
  The meaning of the individual context fields is the same as
  their counterparts in the helper protocol; see the section below
  for a description of each field.
 </p>
 <div class="paragraph"><p>The <tt>helpers</tt> member of the struct is a <tt>string_list</tt> of helpers. Each
 string specifies an external helper which will be run, in order, to
 either acquire or store credentials. See the section on credential
 helpers below.</p></div>
 <div class="paragraph"><p>This struct should always be initialized with <tt>CREDENTIAL_INIT</tt> or
 <tt>credential_init</tt>.</p></div>
 </dd>
 </dl></div>
 </div>
 <h2 id="_functions">Functions</h2>
 <div class="sectionbody">
 <div class="dlist"><dl>
 <dt class="hdlist1">
 <tt>credential_init</tt>
 </dt>
 <dd>
 <p>
  Initialize a credential structure, setting all fields to empty.
 </p>
 </dd>
 <dt class="hdlist1">
 <tt>credential_clear</tt>
 </dt>
 <dd>
 <p>
  Free any resources associated with the credential structure,
  returning it to a pristine initialized state.
 </p>
 </dd>
 <dt class="hdlist1">
 <tt>credential_fill</tt>
 </dt>
 <dd>
 <p>
  Instruct the credential subsystem to fill the username and
  password fields of the passed credential struct by first
  consulting helpers, then asking the user. After this function
  returns, the username and password fields of the credential are
  guaranteed to be non-NULL. If an error occurs, the function will
  die().
 </p>
 </dd>
 <dt class="hdlist1">
 <tt>credential_reject</tt>
 </dt>
 <dd>
 <p>
  Inform the credential subsystem that the provided credentials
  have been rejected. This will cause the credential subsystem to
  notify any helpers of the rejection (which allows them, for
  example, to purge the invalid credentials from storage). It
  will also free() the username and password fields of the
  credential and set them to NULL (readying the credential for
  another call to <tt>credential_fill</tt>). Any errors from helpers are
  ignored.
 </p>
 </dd>
 <dt class="hdlist1">
 <tt>credential_approve</tt>
 </dt>
 <dd>
 <p>
  Inform the credential subsystem that the provided credentials
  were successfully used for authentication. This will cause the
  credential subsystem to notify any helpers of the approval, so
  that they may store the result to be used again. Any errors
  from helpers are ignored.
 </p>
 </dd>
 <dt class="hdlist1">
 <tt>credential_from_url</tt>
 </dt>
 <dd>
 <p>
  Parse a URL into broken-down credential fields.
 </p>
 </dd>
 </dl></div>
 </div>
 <h2 id="_example">Example</h2>
 <div class="sectionbody">
 <div class="paragraph"><p>The example below shows how the functions of the credential API could be
 used to login to a fictitious "foo" service on a remote host:</p></div>
 <div class="listingblock">
 <div class="content">
 <pre><tt>int foo_login(struct foo_connection *f)
 {
  int status;
  /*
  * Create a credential with some context; we don't yet know the
  * username or password.
  */

  struct credential c = CREDENTIAL_INIT;
  c.protocol = xstrdup("foo");
  c.host = xstrdup(f-&gt;hostname);

  /*
  * Fill in the username and password fields by contacting
  * helpers and/or asking the user. The function will die if it
  * fails.
  */
  credential_fill(&amp;c);

  /*
  * Otherwise, we have a username and password. Try to use it.
  */
  status = send_foo_login(f, c.username, c.password);
  switch (status) {
  case FOO_OK:
  /* It worked. Store the credential for later use. */
  credential_accept(&amp;c);
  break;
  case FOO_BAD_LOGIN:
  /* Erase the credential from storage so we don't try it
  * again. */
  credential_reject(&amp;c);
  break;
  default:
  /*
  * Some other error occured. We don't know if the
  * credential is good or bad, so report nothing to the
  * credential subsystem.
  */
  }

  /* Free any associated resources. */
  credential_clear(&amp;c);

  return status;
 }</tt></pre>
 </div></div>
 </div>
 <h2 id="_credential_helpers">Credential Helpers</h2>
 <div class="sectionbody">
 <div class="paragraph"><p>Credential helpers are programs executed by git to fetch or save
 credentials from and to long-term storage (where "long-term" is simply
 longer than a single git process; e.g., credentials may be stored
 in-memory for a few minutes, or indefinitely on disk).</p></div>
 <div class="paragraph"><p>Each helper is specified by a single string. The string is transformed
 by git into a command to be executed using these rules:</p></div>
 <div class="olist arabic"><ol class="arabic">
 <li>
 <p>
 If the helper string begins with "!", it is considered a shell
  snippet, and everything after the "!" becomes the command.
 </p>
 </li>
 <li>
 <p>
 Otherwise, if the helper string begins with an absolute path, the
  verbatim helper string becomes the command.
 </p>
 </li>
 <li>
 <p>
 Otherwise, the string "git credential-" is prepended to the helper
  string, and the result becomes the command.
 </p>
 </li>
 </ol></div>
 <div class="paragraph"><p>The resulting command then has an "operation" argument appended to it
 (see below for details), and the result is executed by the shell.</p></div>
 <div class="paragraph"><p>Here are some example specifications:</p></div>
 <div class="listingblock">
 <div class="content">
 <pre><tt># run "git credential-foo"
 foo

 # same as above, but pass an argument to the helper
 foo --bar=baz

 # the arguments are parsed by the shell, so use shell
 # quoting if necessary
 foo --bar="whitespace arg"

 # you can also use an absolute path, which will not use the git wrapper
 /path/to/my/helper --with-arguments

 # or you can specify your own shell snippet
 !f() { echo "password=`cat $HOME/.secret`"; }; f</tt></pre>
 </div></div>
 <div class="paragraph"><p>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 <tt>git config credential.helper $NAME</tt>.</p></div>
 <div class="paragraph"><p>When a helper is executed, it will have one "operation" argument
 appended to its command line, which is one of:</p></div>
 <div class="dlist"><dl>
 <dt class="hdlist1">
 <tt>get</tt>
 </dt>
 <dd>
 <p>
  Return a matching credential, if any exists.
 </p>
 </dd>
 <dt class="hdlist1">
 <tt>store</tt>
 </dt>
 <dd>
 <p>
  Store the credential, if applicable to the helper.
 </p>
 </dd>
 <dt class="hdlist1">
 <tt>erase</tt>
 </dt>
 <dd>
 <p>
  Remove a matching credential, if any, from the helper&#8217;s storage.
 </p>
 </dd>
 </dl></div>
 <div class="paragraph"><p>The details of the credential will be provided on the helper&#8217;s stdin
 stream. The credential is split into a set of named attributes.
 Attributes are provided to the helper, one per line. Each attribute is
 specified by a key-value pair, separated by an <tt>=</tt> (equals) sign,
 followed by a newline. The key may contain any bytes except <tt>=</tt>,
 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.</p></div>
 <div class="paragraph"><p>Git will send the following attributes (but may not send all of
 them for a given credential; for example, a <tt>host</tt> attribute makes no
 sense when dealing with a non-network protocol):</p></div>
 <div class="dlist"><dl>
 <dt class="hdlist1">
 <tt>protocol</tt>
 </dt>
 <dd>
 <p>
  The protocol over which the credential will be used (e.g.,
  <tt>https</tt>).
 </p>
 </dd>
 <dt class="hdlist1">
 <tt>host</tt>
 </dt>
 <dd>
 <p>
  The remote hostname for a network credential.
 </p>
 </dd>
 <dt class="hdlist1">
 <tt>path</tt>
 </dt>
 <dd>
 <p>
  The path with which the credential will be used. E.g., for
  accessing a remote https repository, this will be the
  repository&#8217;s path on the server.
 </p>
 </dd>
 <dt class="hdlist1">
 <tt>username</tt>
 </dt>
 <dd>
 <p>
  The credential&#8217;s username, if we already have one (e.g., from a
  URL, from the user, or from a previously run helper).
 </p>
 </dd>
 <dt class="hdlist1">
 <tt>password</tt>
 </dt>
 <dd>
 <p>
  The credential&#8217;s password, if we are asking it to be stored.
 </p>
 </dd>
 </dl></div>
 <div class="paragraph"><p>For a <tt>get</tt> operation, the helper should produce a list of attributes
 on stdout in the same format. A helper is free to produce a subset, or
 even no values at all if it has nothing useful to provide. Any provided
 attributes will overwrite those already known about by git.</p></div>
 <div class="paragraph"><p>For a <tt>store</tt> or <tt>erase</tt> operation, the helper&#8217;s output is ignored.
 If it fails to perform the requested operation, it may complain to
 stderr to inform the user. If it does not support the requested
 operation (e.g., a read-only store), it should silently ignore the
 request.</p></div>
 <div class="paragraph"><p>If a helper receives any other operation, it should silently ignore the
 request. This leaves room for future operations to be added (older
 helpers will just ignore the new requests).</p></div>
 </div>
 </div>
 <div id="footnotes"><hr /></div>
 <div id="footer">
 <div id="footer-text">
 Last updated 2011-12-21 14:30:17 PDT
 </div>
 </div>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
	"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<meta name="generator" content="AsciiDoc 8.5.2" />
	<title>credentials API</title>
	<style type="text/css">
	/* Debug borders */
	p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
	/*
	border: 1px solid red;
	*/
	}

	body {
	margin: 1em 5% 1em 5%;
	}

	a {
	color: blue;
	text-decoration: underline;
	}
	a:visited {
	color: fuchsia;
	}

	em {
	font-style: italic;
	color: navy;
	}

	strong {
	font-weight: bold;
	color: #083194;
	}

	tt {
	color: navy;
	}

	h1, h2, h3, h4, h5, h6 {
	color: #527bbd;
	font-family: sans-serif;
	margin-top: 1.2em;
	margin-bottom: 0.5em;
	line-height: 1.3;
	}

	h1, h2, h3 {
	border-bottom: 2px solid silver;
	}
	h2 {
	padding-top: 0.5em;
	}
	h3 {
	float: left;
	}
	h3 + * {
	clear: left;
	}

	div.sectionbody {
	font-family: serif;
	margin-left: 0;
	}

	hr {
	border: 1px solid silver;
	}

	p {
	margin-top: 0.5em;
	margin-bottom: 0.5em;
	}

	ul, ol, li > p {
	margin-top: 0;
	}

	pre {
	padding: 0;
	margin: 0;
	}

	span#author {
	color: #527bbd;
	font-family: sans-serif;
	font-weight: bold;
	font-size: 1.1em;
	}
	span#email {
	}
	span#revnumber, span#revdate, span#revremark {
	font-family: sans-serif;
	}

	div#footer {
	font-family: sans-serif;
	font-size: small;
	border-top: 2px solid silver;
	padding-top: 0.5em;
	margin-top: 4.0em;
	}
	div#footer-text {
	float: left;
	padding-bottom: 0.5em;
	}
	div#footer-badges {
	float: right;
	padding-bottom: 0.5em;
	}

	div#preamble {
	margin-top: 1.5em;
	margin-bottom: 1.5em;
	}
	div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
	div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
	div.admonitionblock {
	margin-top: 1.0em;
	margin-bottom: 1.5em;
	}
	div.admonitionblock {
	margin-top: 2.0em;
	margin-bottom: 2.0em;
	margin-right: 10%;
	color: #606060;
	}

	div.content { /* Block element content. */
	padding: 0;
	}

	/* Block element titles. */
	div.title, caption.title {
	color: #527bbd;
	font-family: sans-serif;
	font-weight: bold;
	text-align: left;
	margin-top: 1.0em;
	margin-bottom: 0.5em;
	}
	div.title + * {
	margin-top: 0;
	}

	td div.title:first-child {
	margin-top: 0.0em;
	}
	div.content div.title:first-child {
	margin-top: 0.0em;
	}
	div.content + div.title {
	margin-top: 0.0em;
	}

	div.sidebarblock > div.content {
	background: #ffffee;
	border: 1px solid silver;
	padding: 0.5em;
	}

	div.listingblock > div.content {
	border: 1px solid silver;
	background: #f4f4f4;
	padding: 0.5em;
	}

	div.quoteblock, div.verseblock {
	padding-left: 1.0em;
	margin-left: 1.0em;
	margin-right: 10%;
	border-left: 5px solid #dddddd;
	color: #777777;
	}

	div.quoteblock > div.attribution {
	padding-top: 0.5em;
	text-align: right;
	}

	div.verseblock > div.content {
	white-space: pre;
	}
	div.verseblock > div.attribution {
	padding-top: 0.75em;
	text-align: left;
	}
	/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
	div.verseblock + div.attribution {
	text-align: left;
	}

	div.admonitionblock .icon {
	vertical-align: top;
	font-size: 1.1em;
	font-weight: bold;
	text-decoration: underline;
	color: #527bbd;
	padding-right: 0.5em;
	}
	div.admonitionblock td.content {
	padding-left: 0.5em;
	border-left: 3px solid #dddddd;
	}

	div.exampleblock > div.content {
	border-left: 3px solid #dddddd;
	padding-left: 0.5em;
	}

	div.imageblock div.content { padding-left: 0; }
	span.image img { border-style: none; }
	a.image:visited { color: white; }

	dl {
	margin-top: 0.8em;
	margin-bottom: 0.8em;
	}
	dt {
	margin-top: 0.5em;
	margin-bottom: 0;
	font-style: normal;
	color: navy;
	}
	dd > *:first-child {
	margin-top: 0.1em;
	}

	ul, ol {
	list-style-position: outside;
	}
	ol.arabic {
	list-style-type: decimal;
	}
	ol.loweralpha {
	list-style-type: lower-alpha;
	}
	ol.upperalpha {
	list-style-type: upper-alpha;
	}
	ol.lowerroman {
	list-style-type: lower-roman;
	}
	ol.upperroman {
	list-style-type: upper-roman;
	}

	div.compact ul, div.compact ol,
	div.compact p, div.compact p,
	div.compact div, div.compact div {
	margin-top: 0.1em;
	margin-bottom: 0.1em;
	}

	div.tableblock > table {
	border: 3px solid #527bbd;
	}
	thead, p.table.header {
	font-family: sans-serif;
	font-weight: bold;
	}
	tfoot {
	font-weight: bold;
	}
	td > div.verse {
	white-space: pre;
	}
	p.table {
	margin-top: 0;
	}
	/* Because the table frame attribute is overriden by CSS in most browsers. */
	div.tableblock > table[frame="void"] {
	border-style: none;
	}
	div.tableblock > table[frame="hsides"] {
	border-left-style: none;
	border-right-style: none;
	}
	div.tableblock > table[frame="vsides"] {
	border-top-style: none;
	border-bottom-style: none;
	}


	div.hdlist {
	margin-top: 0.8em;
	margin-bottom: 0.8em;
	}
	div.hdlist tr {
	padding-bottom: 15px;
	}
	dt.hdlist1.strong, td.hdlist1.strong {
	font-weight: bold;
	}
	td.hdlist1 {
	vertical-align: top;
	font-style: normal;
	padding-right: 0.8em;
	color: navy;
	}
	td.hdlist2 {
	vertical-align: top;
	}
	div.hdlist.compact tr {
	margin: 0;
	padding-bottom: 0;
	}

	.comment {
	background: yellow;
	}

	.footnote, .footnoteref {
	font-size: 0.8em;
	}

	span.footnote, span.footnoteref {
	vertical-align: super;
	}

	#footnotes {
	margin: 20px 0 20px 0;
	padding: 7px 0 0 0;
	}

	#footnotes div.footnote {
	margin: 0 0 5px 0;
	}

	#footnotes hr {
	border: none;
	border-top: 1px solid silver;
	height: 1px;
	text-align: left;
	margin-left: 0;
	width: 20%;
	min-width: 100px;
	}


	@media print {
	div#footer-badges { display: none; }
	}

	div#toc {
	margin-bottom: 2.5em;
	}

	div#toctitle {
	color: #527bbd;
	font-family: sans-serif;
	font-size: 1.1em;
	font-weight: bold;
	margin-top: 1.0em;
	margin-bottom: 0.1em;
	}

	div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
	margin-top: 0;
	margin-bottom: 0;
	}
	div.toclevel2 {
	margin-left: 2em;
	font-size: 0.9em;
	}
	div.toclevel3 {
	margin-left: 4em;
	font-size: 0.9em;
	}
	div.toclevel4 {
	margin-left: 6em;
	font-size: 0.9em;
	}
	/* Workarounds for IE6's broken and incomplete CSS2. */

	div.sidebar-content {
	background: #ffffee;
	border: 1px solid silver;
	padding: 0.5em;
	}
	div.sidebar-title, div.image-title {
	color: #527bbd;
	font-family: sans-serif;
	font-weight: bold;
	margin-top: 0.0em;
	margin-bottom: 0.5em;
	}

	div.listingblock div.content {
	border: 1px solid silver;
	background: #f4f4f4;
	padding: 0.5em;
	}

	div.quoteblock-attribution {
	padding-top: 0.5em;
	text-align: right;
	}

	div.verseblock-content {
	white-space: pre;
	}
	div.verseblock-attribution {
	padding-top: 0.75em;
	text-align: left;
	}

	div.exampleblock-content {
	border-left: 3px solid #dddddd;
	padding-left: 0.5em;
	}

	/* IE6 sets dynamically generated links as visited. */
	div#toc a:visited { color: blue; }
	</style>
	<script type="text/javascript">
	/<![CDATA[/
	window.onload = function(){asciidoc.footnotes();}
	var asciidoc = { // Namespace.

	/////////////////////////////////////////////////////////////////////
	// Table Of Contents generator
	/////////////////////////////////////////////////////////////////////

	/* Author: Mihai Bazon, September 2002
	* http://students.infoiasi.ro/~mishoo
	*
	* Table Of Content generator
	* Version: 0.4
	*
	* Feel free to use this script under the terms of the GNU General Public
	* License, as long as you do not remove or alter this notice.
	*/

	/* modified by Troy D. Hanson, September 2006. License: GPL */
	/* modified by Stuart Rackham, 2006, 2009. License: GPL */

	// toclevels = 1..4.
	toc: function (toclevels) {

	function getText(el) {
	var text = "";
	for (var i = el.firstChild; i != null; i = i.nextSibling) {
	if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
	text += i.data;
	else if (i.firstChild != null)
	text += getText(i);
	}
	return text;
	}

	function TocEntry(el, text, toclevel) {
	this.element = el;
	this.text = text;
	this.toclevel = toclevel;
	}

	function tocEntries(el, toclevels) {
	var result = new Array;
	var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
	// Function that scans the DOM tree for header elements (the DOM2
	// nodeIterator API would be a better technique but not supported by all
	// browsers).
	var iterate = function (el) {
	for (var i = el.firstChild; i != null; i = i.nextSibling) {
	if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
	var mo = re.exec(i.tagName);
	if (mo && (i.getAttribute("class") \|\| i.getAttribute("className")) != "float") {
	result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
	}
	iterate(i);
	}
	}
	}
	iterate(el);
	return result;
	}

	var toc = document.getElementById("toc");
	var entries = tocEntries(document.getElementById("content"), toclevels);
	for (var i = 0; i < entries.length; ++i) {
	var entry = entries[i];
	if (entry.element.id == "")
	entry.element.id = "_toc_" + i;
	var a = document.createElement("a");
	a.href = "#" + entry.element.id;
	a.appendChild(document.createTextNode(entry.text));
	var div = document.createElement("div");
	div.appendChild(a);
	div.className = "toclevel" + entry.toclevel;
	toc.appendChild(div);
	}
	if (entries.length == 0)
	toc.parentNode.removeChild(toc);
	},


	/////////////////////////////////////////////////////////////////////
	// Footnotes generator
	/////////////////////////////////////////////////////////////////////

	/* Based on footnote generation code from:
	* http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
	*/

	footnotes: function () {
	var cont = document.getElementById("content");
	var noteholder = document.getElementById("footnotes");
	var spans = cont.getElementsByTagName("span");
	var refs = {};
	var n = 0;
	for (i=0; i<spans.length; i++) {
	if (spans[i].className == "footnote") {
	n++;
	// Use [\s\S] in place of . so multi-line matches work.
	// Because JavaScript has no s (dotall) regex flag.
	note = spans[i].innerHTML.match(/\s\[([\s\S])]\s*/)[1];
	noteholder.innerHTML +=
	"<div class='footnote' id='_footnote_" + n + "'>" +
	"<a href='#_footnoteref_" + n + "' title='Return to text'>" +
	n + "</a>. " + note + "</div>";
	spans[i].innerHTML =
	"[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
	"' title='View footnote' class='footnote'>" + n + "</a>]";
	var id =spans[i].getAttribute("id");
	if (id != null) refs["#"+id] = n;
	}
	}
	if (n == 0)
	noteholder.parentNode.removeChild(noteholder);
	else {
	// Process footnoterefs.
	for (i=0; i<spans.length; i++) {
	if (spans[i].className == "footnoteref") {
	var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
	href = href.match(/#.*/)[0]; // Because IE return full URL.
	n = refs[href];
	spans[i].innerHTML =
	"[<a href='#_footnote_" + n +
	"' title='View footnote' class='footnote'>" + n + "</a>]";
	}
	}
	}
	}

	}
	/]]>/
	</script>
	</head>
	<body>
	<div id="header">
	<h1>credentials API</h1>
	</div>
	<div id="content">
	<div id="preamble">
	<div class="sectionbody">
	<div class="paragraph"><p>The credentials API provides an abstracted way of gathering username and
	password credentials from the user (even though credentials in the wider
	world can take many forms, in this document the word "credential" always
	refers to a username and password pair).</p></div>
	</div>
	</div>
	<h2 id="_data_structures">Data Structures</h2>
	<div class="sectionbody">
	<div class="dlist"><dl>
	<dt class="hdlist1">
	<tt>struct credential</tt>
	</dt>
	<dd>
	<p>
	This struct represents a single username/password combination
	along with any associated context. All string fields should be
	heap-allocated (or NULL if they are not known or not applicable).
	The meaning of the individual context fields is the same as
	their counterparts in the helper protocol; see the section below
	for a description of each field.
	</p>
	<div class="paragraph"><p>The <tt>helpers</tt> member of the struct is a <tt>string_list</tt> of helpers. Each
	string specifies an external helper which will be run, in order, to
	either acquire or store credentials. See the section on credential
	helpers below.</p></div>
	<div class="paragraph"><p>This struct should always be initialized with <tt>CREDENTIAL_INIT</tt> or
	<tt>credential_init</tt>.</p></div>
	</dd>
	</dl></div>
	</div>
	<h2 id="_functions">Functions</h2>
	<div class="sectionbody">
	<div class="dlist"><dl>
	<dt class="hdlist1">
	<tt>credential_init</tt>
	</dt>
	<dd>
	<p>
	Initialize a credential structure, setting all fields to empty.
	</p>
	</dd>
	<dt class="hdlist1">
	<tt>credential_clear</tt>
	</dt>
	<dd>
	<p>
	Free any resources associated with the credential structure,
	returning it to a pristine initialized state.
	</p>
	</dd>
	<dt class="hdlist1">
	<tt>credential_fill</tt>
	</dt>
	<dd>
	<p>
	Instruct the credential subsystem to fill the username and
	password fields of the passed credential struct by first
	consulting helpers, then asking the user. After this function
	returns, the username and password fields of the credential are
	guaranteed to be non-NULL. If an error occurs, the function will
	die().
	</p>
	</dd>
	<dt class="hdlist1">
	<tt>credential_reject</tt>
	</dt>
	<dd>
	<p>
	Inform the credential subsystem that the provided credentials
	have been rejected. This will cause the credential subsystem to
	notify any helpers of the rejection (which allows them, for
	example, to purge the invalid credentials from storage). It
	will also free() the username and password fields of the
	credential and set them to NULL (readying the credential for
	another call to <tt>credential_fill</tt>). Any errors from helpers are
	ignored.
	</p>
	</dd>
	<dt class="hdlist1">
	<tt>credential_approve</tt>
	</dt>
	<dd>
	<p>
	Inform the credential subsystem that the provided credentials
	were successfully used for authentication. This will cause the
	credential subsystem to notify any helpers of the approval, so
	that they may store the result to be used again. Any errors
	from helpers are ignored.
	</p>
	</dd>
	<dt class="hdlist1">
	<tt>credential_from_url</tt>
	</dt>
	<dd>
	<p>
	Parse a URL into broken-down credential fields.
	</p>
	</dd>
	</dl></div>
	</div>
	<h2 id="_example">Example</h2>
	<div class="sectionbody">
	<div class="paragraph"><p>The example below shows how the functions of the credential API could be
	used to login to a fictitious "foo" service on a remote host:</p></div>
	<div class="listingblock">
	<div class="content">
	<pre><tt>int foo_login(struct foo_connection *f)
	{
	int status;
	/*
	* Create a credential with some context; we don't yet know the
	* username or password.
	*/

	struct credential c = CREDENTIAL_INIT;
	c.protocol = xstrdup("foo");
	c.host = xstrdup(f->hostname);

	/*
	* Fill in the username and password fields by contacting
	* helpers and/or asking the user. The function will die if it
	* fails.
	*/
	credential_fill(&c);

	/*
	* Otherwise, we have a username and password. Try to use it.
	*/
	status = send_foo_login(f, c.username, c.password);
	switch (status) {
	case FOO_OK:
	/* It worked. Store the credential for later use. */
	credential_accept(&c);
	break;
	case FOO_BAD_LOGIN:
	/* Erase the credential from storage so we don't try it
	* again. */
	credential_reject(&c);
	break;
	default:
	/*
	* Some other error occured. We don't know if the
	* credential is good or bad, so report nothing to the
	* credential subsystem.
	*/
	}

	/* Free any associated resources. */
	credential_clear(&c);

	return status;
	}</tt></pre>
	</div></div>
	</div>
	<h2 id="_credential_helpers">Credential Helpers</h2>
	<div class="sectionbody">
	<div class="paragraph"><p>Credential helpers are programs executed by git to fetch or save
	credentials from and to long-term storage (where "long-term" is simply
	longer than a single git process; e.g., credentials may be stored
	in-memory for a few minutes, or indefinitely on disk).</p></div>
	<div class="paragraph"><p>Each helper is specified by a single string. The string is transformed
	by git into a command to be executed using these rules:</p></div>
	<div class="olist arabic"><ol class="arabic">
	<li>
	<p>
	If the helper string begins with "!", it is considered a shell
	snippet, and everything after the "!" becomes the command.
	</p>
	</li>
	<li>
	<p>
	Otherwise, if the helper string begins with an absolute path, the
	verbatim helper string becomes the command.
	</p>
	</li>
	<li>
	<p>
	Otherwise, the string "git credential-" is prepended to the helper
	string, and the result becomes the command.
	</p>
	</li>
	</ol></div>
	<div class="paragraph"><p>The resulting command then has an "operation" argument appended to it
	(see below for details), and the result is executed by the shell.</p></div>
	<div class="paragraph"><p>Here are some example specifications:</p></div>
	<div class="listingblock">
	<div class="content">
	<pre><tt># run "git credential-foo"
	foo

	# same as above, but pass an argument to the helper
	foo --bar=baz

	# the arguments are parsed by the shell, so use shell
	# quoting if necessary
	foo --bar="whitespace arg"

	# you can also use an absolute path, which will not use the git wrapper
	/path/to/my/helper --with-arguments

	# or you can specify your own shell snippet
	!f() { echo "password=`cat $HOME/.secret`"; }; f</tt></pre>
	</div></div>
	<div class="paragraph"><p>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 <tt>git config credential.helper $NAME</tt>.</p></div>
	<div class="paragraph"><p>When a helper is executed, it will have one "operation" argument
	appended to its command line, which is one of:</p></div>
	<div class="dlist"><dl>
	<dt class="hdlist1">
	<tt>get</tt>
	</dt>
	<dd>
	<p>
	Return a matching credential, if any exists.
	</p>
	</dd>
	<dt class="hdlist1">
	<tt>store</tt>
	</dt>
	<dd>
	<p>
	Store the credential, if applicable to the helper.
	</p>
	</dd>
	<dt class="hdlist1">
	<tt>erase</tt>
	</dt>
	<dd>
	<p>
	Remove a matching credential, if any, from the helper’s storage.
	</p>
	</dd>
	</dl></div>
	<div class="paragraph"><p>The details of the credential will be provided on the helper’s stdin
	stream. The credential is split into a set of named attributes.
	Attributes are provided to the helper, one per line. Each attribute is
	specified by a key-value pair, separated by an <tt>=</tt> (equals) sign,
	followed by a newline. The key may contain any bytes except <tt>=</tt>,
	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.</p></div>
	<div class="paragraph"><p>Git will send the following attributes (but may not send all of
	them for a given credential; for example, a <tt>host</tt> attribute makes no
	sense when dealing with a non-network protocol):</p></div>
	<div class="dlist"><dl>
	<dt class="hdlist1">
	<tt>protocol</tt>
	</dt>
	<dd>
	<p>
	The protocol over which the credential will be used (e.g.,
	<tt>https</tt>).
	</p>
	</dd>
	<dt class="hdlist1">
	<tt>host</tt>
	</dt>
	<dd>
	<p>
	The remote hostname for a network credential.
	</p>
	</dd>
	<dt class="hdlist1">
	<tt>path</tt>
	</dt>
	<dd>
	<p>
	The path with which the credential will be used. E.g., for
	accessing a remote https repository, this will be the
	repository’s path on the server.
	</p>
	</dd>
	<dt class="hdlist1">
	<tt>username</tt>
	</dt>
	<dd>
	<p>
	The credential’s username, if we already have one (e.g., from a
	URL, from the user, or from a previously run helper).
	</p>
	</dd>
	<dt class="hdlist1">
	<tt>password</tt>
	</dt>
	<dd>
	<p>
	The credential’s password, if we are asking it to be stored.
	</p>
	</dd>
	</dl></div>
	<div class="paragraph"><p>For a <tt>get</tt> operation, the helper should produce a list of attributes
	on stdout in the same format. A helper is free to produce a subset, or
	even no values at all if it has nothing useful to provide. Any provided
	attributes will overwrite those already known about by git.</p></div>
	<div class="paragraph"><p>For a <tt>store</tt> or <tt>erase</tt> operation, the helper’s output is ignored.
	If it fails to perform the requested operation, it may complain to
	stderr to inform the user. If it does not support the requested
	operation (e.g., a read-only store), it should silently ignore the
	request.</p></div>
	<div class="paragraph"><p>If a helper receives any other operation, it should silently ignore the
	request. This leaves room for future operations to be added (older
	helpers will just ignore the new requests).</p></div>
	</div>
	</div>
	<div id="footnotes"><hr /></div>
	<div id="footer">
	<div id="footer-text">
	Last updated 2011-12-21 14:30:17 PDT
	</div>
	</div>
	</body>
	</html>