EVOLUTION-MANAGER
Edit File: package.html
<!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <meta name="generator" content="pandoc" /> <meta http-equiv="X-UA-Compatible" content="IE=EDGE" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <title>gitcreds for package authors</title> <script>// Pandoc 2.9 adds attributes on both header and div. We remove the former (to // be compatible with the behavior of Pandoc < 2.8). document.addEventListener('DOMContentLoaded', function(e) { var hs = document.querySelectorAll("div.section[class*='level'] > :first-child"); var i, h, a; for (i = 0; i < hs.length; i++) { h = hs[i]; if (!/^h[1-6]$/i.test(h.tagName)) continue; // it should be a header h1-h6 a = h.attributes; while (a.length > 0) h.removeAttribute(a[0].name); } }); </script> <style type="text/css"> code{white-space: pre-wrap;} span.smallcaps{font-variant: small-caps;} span.underline{text-decoration: underline;} div.column{display: inline-block; vertical-align: top; width: 50%;} div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} ul.task-list{list-style: none;} </style> <style type="text/css"> code { white-space: pre; } .sourceCode { overflow: visible; } </style> <style type="text/css" data-origin="pandoc"> pre > code.sourceCode { white-space: pre; position: relative; } pre > code.sourceCode > span { display: inline-block; line-height: 1.25; } pre > code.sourceCode > span:empty { height: 1.2em; } .sourceCode { overflow: visible; } code.sourceCode > span { color: inherit; text-decoration: inherit; } div.sourceCode { margin: 1em 0; } pre.sourceCode { margin: 0; } @media screen { div.sourceCode { overflow: auto; } } @media print { pre > code.sourceCode { white-space: pre-wrap; } pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; } } pre.numberSource code { counter-reset: source-line 0; } pre.numberSource code > span { position: relative; left: -4em; counter-increment: source-line; } pre.numberSource code > span > a:first-child::before { content: counter(source-line); position: relative; left: -1em; text-align: right; vertical-align: baseline; border: none; display: inline-block; -webkit-touch-callout: none; -webkit-user-select: none; -khtml-user-select: none; -moz-user-select: none; -ms-user-select: none; user-select: none; padding: 0 4px; width: 4em; color: #aaaaaa; } pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; } div.sourceCode { } @media screen { pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; } } code span.al { color: #ff0000; font-weight: bold; } /* Alert */ code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */ code span.at { color: #7d9029; } /* Attribute */ code span.bn { color: #40a070; } /* BaseN */ code span.bu { } /* BuiltIn */ code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */ code span.ch { color: #4070a0; } /* Char */ code span.cn { color: #880000; } /* Constant */ code span.co { color: #60a0b0; font-style: italic; } /* Comment */ code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */ code span.do { color: #ba2121; font-style: italic; } /* Documentation */ code span.dt { color: #902000; } /* DataType */ code span.dv { color: #40a070; } /* DecVal */ code span.er { color: #ff0000; font-weight: bold; } /* Error */ code span.ex { } /* Extension */ code span.fl { color: #40a070; } /* Float */ code span.fu { color: #06287e; } /* Function */ code span.im { } /* Import */ code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */ code span.kw { color: #007020; font-weight: bold; } /* Keyword */ code span.op { color: #666666; } /* Operator */ code span.ot { color: #007020; } /* Other */ code span.pp { color: #bc7a00; } /* Preprocessor */ code span.sc { color: #4070a0; } /* SpecialChar */ code span.ss { color: #bb6688; } /* SpecialString */ code span.st { color: #4070a0; } /* String */ code span.va { color: #19177c; } /* Variable */ code span.vs { color: #4070a0; } /* VerbatimString */ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */ </style> <script> // apply pandoc div.sourceCode style to pre.sourceCode instead (function() { var sheets = document.styleSheets; for (var i = 0; i < sheets.length; i++) { if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue; try { var rules = sheets[i].cssRules; } catch (e) { continue; } var j = 0; while (j < rules.length) { var rule = rules[j]; // check if there is a div.sourceCode rule if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") { j++; continue; } var style = rule.style.cssText; // check if color or background-color is set if (rule.style.color === '' && rule.style.backgroundColor === '') { j++; continue; } // replace div.sourceCode by a pre.sourceCode rule sheets[i].deleteRule(j); sheets[i].insertRule('pre.sourceCode{' + style + '}', j); } } })(); </script> <style type="text/css">body { background-color: #fff; margin: 1em auto; max-width: 700px; overflow: visible; padding-left: 2em; padding-right: 2em; font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; font-size: 14px; line-height: 1.35; } #TOC { clear: both; margin: 0 0 10px 10px; padding: 4px; width: 400px; border: 1px solid #CCCCCC; border-radius: 5px; background-color: #f6f6f6; font-size: 13px; line-height: 1.3; } #TOC .toctitle { font-weight: bold; font-size: 15px; margin-left: 5px; } #TOC ul { padding-left: 40px; margin-left: -1.5em; margin-top: 5px; margin-bottom: 5px; } #TOC ul ul { margin-left: -2em; } #TOC li { line-height: 16px; } table { margin: 1em auto; border-width: 1px; border-color: #DDDDDD; border-style: outset; border-collapse: collapse; } table th { border-width: 2px; padding: 5px; border-style: inset; } table td { border-width: 1px; border-style: inset; line-height: 18px; padding: 5px 5px; } table, table th, table td { border-left-style: none; border-right-style: none; } table thead, table tr.even { background-color: #f7f7f7; } p { margin: 0.5em 0; } blockquote { background-color: #f6f6f6; padding: 0.25em 0.75em; } hr { border-style: solid; border: none; border-top: 1px solid #777; margin: 28px 0; } dl { margin-left: 0; } dl dd { margin-bottom: 13px; margin-left: 13px; } dl dt { font-weight: bold; } ul { margin-top: 0; } ul li { list-style: circle outside; } ul ul { margin-bottom: 0; } pre, code { background-color: #f7f7f7; border-radius: 3px; color: #333; white-space: pre-wrap; } pre { border-radius: 3px; margin: 5px 0px 10px 0px; padding: 10px; } pre:not([class]) { background-color: #f7f7f7; } code { font-family: Consolas, Monaco, 'Courier New', monospace; font-size: 85%; } p > code, li > code { padding: 2px 0px; } div.figure { text-align: center; } img { background-color: #FFFFFF; padding: 2px; border: 1px solid #DDDDDD; border-radius: 3px; border: 1px solid #CCCCCC; margin: 0 5px; } h1 { margin-top: 0; font-size: 35px; line-height: 40px; } h2 { border-bottom: 4px solid #f7f7f7; padding-top: 10px; padding-bottom: 2px; font-size: 145%; } h3 { border-bottom: 2px solid #f7f7f7; padding-top: 10px; font-size: 120%; } h4 { border-bottom: 1px solid #f7f7f7; margin-left: 8px; font-size: 105%; } h5, h6 { border-bottom: 1px solid #ccc; font-size: 105%; } a { color: #0033dd; text-decoration: none; } a:hover { color: #6666ff; } a:visited { color: #800080; } a:visited:hover { color: #BB00BB; } a[href^="http:"] { text-decoration: underline; } a[href^="https:"] { text-decoration: underline; } code > span.kw { color: #555; font-weight: bold; } code > span.dt { color: #902000; } code > span.dv { color: #40a070; } code > span.bn { color: #d14; } code > span.fl { color: #d14; } code > span.ch { color: #d14; } code > span.st { color: #d14; } code > span.co { color: #888888; font-style: italic; } code > span.ot { color: #007020; } code > span.al { color: #ff0000; font-weight: bold; } code > span.fu { color: #900; font-weight: bold; } code > span.er { color: #a61717; background-color: #e3d2d2; } </style> </head> <body> <h1 class="title toc-ignore">gitcreds for package authors</h1> <div id="introduction" class="section level2"> <h2>Introduction</h2> <p>If you have a package that queries the GitHub API, or uses git with remote git repositories, then most likely you need to let your users specify their GitHub or git credentials. There are several benefits of using gitcreds to do this:</p> <ul> <li><p>(Re)use the same credentials as command line git, R and the RStudio IDE., etc. Users can set their GitHub token once and use it everywhere.</p></li> <li><p>Users can use the same credentials for multiple R packages.</p></li> <li><p>gitcreds has a cache that makes credential lookup very fast.</p></li> <li><p>Typically more secure than storing passwords and tokens in <code>.Renviron</code> files.</p></li> <li><p>gitcreds supports multiple users and multiple hosts.</p></li> <li><p>If git or credential helpers are not available, e.g. typically on a Linux server, then gitcreds can still use environment variables, and it still supports multiple users and hosts.</p></li> </ul> </div> <div id="the-simple-api" class="section level2"> <h2>The simple API</h2> <p>The simplest way to use gitcreds is to call <code>gitcreds_get()</code> from your package to query credentials, possibly with a custom URL. For setting new credentials, you can point your users to <code>gitcreds_set()</code>.</p> <div id="errors-from-the-simple-api" class="section level3"> <h3>Errors from the simple API</h3> <p>If you are using the simple API, gitcreds may throw the following classed errors and your package might want to handle:</p> <ul> <li><p><code>gitcreds_nogit_error</code> if git it not available on the system.</p></li> <li><p><code>gitcreds_no_credentials</code> if git did not find any credentials for the specified URL. The URL is stored in the error, under <code>url</code>.</p></li> <li><p><code>git_error</code> if a git command returned some error. The following information is stored in the error object:</p> <ul> <li><p><code>args</code> the command line arguments to git,</p></li> <li><p><code>stdout</code> standard output,</p></li> <li><p><code>stderr</code> standard error,</p></li> <li><p><code>status</code> the exit status of the git process.</p></li> </ul></li> <li><p><code>gitcreds_not_interactive_error</code> if <code>gitcreds_set()</code> is called in non-interactive mode.</p></li> <li><p><code>gitcreds_abort_replace_error</code> if the user aborted replacing the existing credentials.</p></li> </ul> </div> </div> <div id="the-low-level-api" class="section level2"> <h2>The low level API</h2> <p>Should you need more flexibility, you can use the <code>gitcreds_approve()</code>, <code>gitcreds_fill()</code> and <code>gitcreds_reject()</code> functions, to add/update, query and remove credentials. We suggest you use the dummy credential helper (see below) for <code>gitcreds_fill()</code>, to avoid git password dialog boxes if a credential is not available.</p> <p>E.g. the low level API makes it possible to implement an alternative to <code>gitcreds_set()</code> , with a different user interface, or a version that also works in non-interactive sessions.</p> <div id="the-dummy-credential-helper" class="section level3"> <h3>The dummy credential helper</h3> <p>In a typical setup, if git does not find credentials for the requested host after querying all defined credential helpers, it’ll ask for a password in a dialog box, or a terminal prompt. It is often best to avoid these, and deal with the situation within R.</p> <p>gitcreds has a dummy credential helper, that always supplies dummy credentials. By default <code>gitcreds_fill()</code> adds this dummy helper to the list of configured credential helpers, and code calling <code>gitcreds_fill()</code> can check if git returned the dummy credentials, meaning that no real credentials were found. This is how the dummy credentials look:</p> <div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="fu">gitcreds_fill</span>(<span class="fu">list</span>(<span class="at">url=</span><span class="st">"https://impossible.com"</span>))</span> <span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="co">#> [1] "protocol=dummy" "host=dummy"</span></span> <span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a><span class="co">#> [3] "username=dummy" "password=dummy get"</span></span></code></pre></div> <p>It is best to look for <code>protocol=dummy</code> as the first line of the git output.</p> </div> <div id="errors-from-the-low-level-api" class="section level3"> <h3>Errors from the low level API</h3> <ul> <li><p><code>git_error</code> if a git command returned some error. The following information is stored in the error object:</p> <ul> <li><p><code>args</code> the command line arguments to git,</p></li> <li><p><code>stdout</code> standard output,</p></li> <li><p><code>stderr</code> standard error,</p></li> <li><p><code>status</code> the exit status of the git process.</p></li> </ul></li> </ul> </div> </div> <div id="testing" class="section level2"> <h2>Testing</h2> <p>If your package uses gitcreds, either directly, or through another package, then you might want to test your package for the the various possible states of the user’s git installation and credential store. gitcreds has some facilities to help you with this.</p> <p>If you want to test your package for a specific output from gitcreds, you can temporarily set the environment variable that gitcreds uses as a cache to the desired value. Use the <code>gitcreds_cache_envvar()</code> function to see which environment variable you need to set for a url:</p> <div class="sourceCode" id="cb2"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a>gitcreds<span class="sc">::</span><span class="fu">gitcreds_cache_envvar</span>(<span class="st">"https://github.com"</span>)</span></code></pre></div> <pre><code>## [1] "GITHUB_PAT_GITHUB_COM"</code></pre> <p>It is easiest to use the withr package to temporarily change this environment variable in a test case:</p> <div class="sourceCode" id="cb4"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="fu">library</span>(testthat)</span> <span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a><span class="fu">test_that</span>(<span class="st">"bad credentials from git"</span>, {</span> <span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a> withr<span class="sc">::</span><span class="fu">local_envvar</span>(<span class="fu">c</span>(<span class="at">GITHUB_PAT_GITHUB_COM =</span> <span class="st">"bad"</span>))</span> <span id="cb4-4"><a href="#cb4-4" aria-hidden="true" tabindex="-1"></a> <span class="co"># Test code that calls gitcreds_get(), potentially downstream.</span></span> <span id="cb4-5"><a href="#cb4-5" aria-hidden="true" tabindex="-1"></a> <span class="co"># gitcreds_get() will return `bad` as the password.</span></span> <span id="cb4-6"><a href="#cb4-6" aria-hidden="true" tabindex="-1"></a> <span class="co"># Illustration:</span></span> <span id="cb4-7"><a href="#cb4-7" aria-hidden="true" tabindex="-1"></a> <span class="fu">expect_equal</span>(</span> <span id="cb4-8"><a href="#cb4-8" aria-hidden="true" tabindex="-1"></a> gitcreds<span class="sc">::</span><span class="fu">gitcreds_get</span>(<span class="st">"https://github.com"</span>)<span class="sc">$</span>password,</span> <span id="cb4-9"><a href="#cb4-9" aria-hidden="true" tabindex="-1"></a> <span class="st">"bad"</span></span> <span id="cb4-10"><a href="#cb4-10" aria-hidden="true" tabindex="-1"></a> )</span> <span id="cb4-11"><a href="#cb4-11" aria-hidden="true" tabindex="-1"></a>})</span></code></pre></div> <pre><code>## Test passed 🥇</code></pre> <p>If you want gitcreds to return a specific credential record, then you can specify the fields of the record in the environment variable, separated by colons. For example:</p> <div class="sourceCode" id="cb6"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="fu">library</span>(testthat)</span> <span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a><span class="fu">test_that</span>(<span class="st">"another GitHub user"</span>, {</span> <span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a> cred <span class="ot"><-</span> <span class="fu">paste0</span>(</span> <span id="cb6-4"><a href="#cb6-4" aria-hidden="true" tabindex="-1"></a> <span class="st">"protocol:https:"</span>,</span> <span id="cb6-5"><a href="#cb6-5" aria-hidden="true" tabindex="-1"></a> <span class="st">"host:github.com:"</span>,</span> <span id="cb6-6"><a href="#cb6-6" aria-hidden="true" tabindex="-1"></a> <span class="st">"username:user1:"</span>,</span> <span id="cb6-7"><a href="#cb6-7" aria-hidden="true" tabindex="-1"></a> <span class="st">"password:secret"</span></span> <span id="cb6-8"><a href="#cb6-8" aria-hidden="true" tabindex="-1"></a> )</span> <span id="cb6-9"><a href="#cb6-9" aria-hidden="true" tabindex="-1"></a> withr<span class="sc">::</span><span class="fu">local_envvar</span>(<span class="fu">c</span>(<span class="at">GITHUB_PAT_GITHUB_COM =</span> cred))</span> <span id="cb6-10"><a href="#cb6-10" aria-hidden="true" tabindex="-1"></a> <span class="co"># Your test code comes here. This is just an illustration:</span></span> <span id="cb6-11"><a href="#cb6-11" aria-hidden="true" tabindex="-1"></a> <span class="fu">print</span>(gitcreds<span class="sc">::</span><span class="fu">gitcreds_get</span>())</span> <span id="cb6-12"><a href="#cb6-12" aria-hidden="true" tabindex="-1"></a> <span class="fu">expect_equal</span>(gitcreds<span class="sc">::</span><span class="fu">gitcreds_get</span>()<span class="sc">$</span>username, <span class="st">"user1"</span>)</span> <span id="cb6-13"><a href="#cb6-13" aria-hidden="true" tabindex="-1"></a>})</span></code></pre></div> <pre><code>## <gitcreds> ## protocol: https ## host : github.com ## username: user1 ## password: <-- hidden --> ## Test passed 🌈</code></pre> <p>If you want gitcreds to fail for a specific host, set the corresponding environment variable to <code>"FAIL"</code>:</p> <div class="sourceCode" id="cb8"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="fu">library</span>(testthat)</span> <span id="cb8-2"><a href="#cb8-2" aria-hidden="true" tabindex="-1"></a><span class="fu">test_that</span>(<span class="st">"no credentials from git"</span>, {</span> <span id="cb8-3"><a href="#cb8-3" aria-hidden="true" tabindex="-1"></a> withr<span class="sc">::</span><span class="fu">local_envvar</span>(<span class="fu">c</span>(<span class="at">GITHUB_PAT_GITHUB_COM =</span> <span class="st">"FAIL"</span>))</span> <span id="cb8-4"><a href="#cb8-4" aria-hidden="true" tabindex="-1"></a> <span class="co"># The test code that calls gitcreds_get() comes here.</span></span> <span id="cb8-5"><a href="#cb8-5" aria-hidden="true" tabindex="-1"></a> <span class="co"># It will fail with error "gitcreds_no_credentials"</span></span> <span id="cb8-6"><a href="#cb8-6" aria-hidden="true" tabindex="-1"></a> <span class="fu">expect_error</span>(</span> <span id="cb8-7"><a href="#cb8-7" aria-hidden="true" tabindex="-1"></a> gitcreds<span class="sc">::</span><span class="fu">gitcreds_get</span>(<span class="st">"https://github.com"</span>),</span> <span id="cb8-8"><a href="#cb8-8" aria-hidden="true" tabindex="-1"></a> <span class="at">class =</span> <span class="st">"gitcreds_no_credentials"</span></span> <span id="cb8-9"><a href="#cb8-9" aria-hidden="true" tabindex="-1"></a> )</span> <span id="cb8-10"><a href="#cb8-10" aria-hidden="true" tabindex="-1"></a>})</span></code></pre></div> <pre><code>## Test passed 😸</code></pre> <p>If you want gitcreds to fail with a specific error, then include the error class after a <code>"FAIL:"</code> prefix, in the environment variable. See the list of possible error classes above. For example:</p> <div class="sourceCode" id="cb10"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="fu">library</span>(testthat)</span> <span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a><span class="fu">test_that</span>(<span class="st">"no git installation"</span>, {</span> <span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a> withr<span class="sc">::</span><span class="fu">local_envvar</span>(<span class="fu">c</span>(</span> <span id="cb10-4"><a href="#cb10-4" aria-hidden="true" tabindex="-1"></a> <span class="at">GITHUB_PAT_GITHUB_COM =</span> <span class="st">"FAIL:gitcreds_nogit_error"</span></span> <span id="cb10-5"><a href="#cb10-5" aria-hidden="true" tabindex="-1"></a> ))</span> <span id="cb10-6"><a href="#cb10-6" aria-hidden="true" tabindex="-1"></a> <span class="co"># Test code that calls gitcreds_get() comes here.</span></span> <span id="cb10-7"><a href="#cb10-7" aria-hidden="true" tabindex="-1"></a> <span class="co"># Illustration:</span></span> <span id="cb10-8"><a href="#cb10-8" aria-hidden="true" tabindex="-1"></a> <span class="fu">expect_error</span>(</span> <span id="cb10-9"><a href="#cb10-9" aria-hidden="true" tabindex="-1"></a> gitcreds<span class="sc">::</span><span class="fu">gitcreds_get</span>(<span class="st">"https://github.com"</span>),</span> <span id="cb10-10"><a href="#cb10-10" aria-hidden="true" tabindex="-1"></a> <span class="at">class =</span> <span class="st">"gitcreds_nogit_error"</span></span> <span id="cb10-11"><a href="#cb10-11" aria-hidden="true" tabindex="-1"></a> )</span> <span id="cb10-12"><a href="#cb10-12" aria-hidden="true" tabindex="-1"></a>})</span></code></pre></div> <pre><code>## Test passed 🎊</code></pre> <p>It is not currently possible to simulate the additional data in the error object, e.g. the standard output of a failed git command. If you need this for a test case, then your test case can call <code>gitcreds_get()</code> directly and you can use the mockery package to make gitcreds fail with the desired error object.</p> </div> <!-- code folding --> <!-- dynamically load mathjax for compatibility with self-contained --> <script> (function () { var script = document.createElement("script"); script.type = "text/javascript"; script.src = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"; document.getElementsByTagName("head")[0].appendChild(script); })(); </script> </body> </html>