| <!doctype html> |
| <html class="no-js" lang="en" dir="ltr"> |
| <head> |
| <meta charset="utf-8"> |
| <meta http-equiv="x-ua-compatible" content="ie=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <title>Getting started with Git - Apache Infrastructure Website</title> |
| <link href="/css/bootstrap.min.css" rel="stylesheet"> |
| <link href="/css/fontawesome.all.min.css" rel="stylesheet"> |
| <link href="/css/headerlink.css" rel="stylesheet"> |
| <script src="/highlight/highlight.min.js"></script> </head> |
| <body class="d-flex flex-column h-100"> |
| <main class="flex-shrink-0"> |
| <div> |
| |
| <!-- nav bar --> |
| <nav class="navbar navbar-expand-lg navbar-dark bg-dark" aria-label="Fifth navbar example"> |
| <div class="container-fluid"> |
| <a class="navbar-brand" href="/"><img src="/images/feather.png" style="height: 32px;"/> Apache Infrastructure</a> |
| <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarADP" aria-controls="navbarADP" aria-expanded="false" aria-label="Toggle navigation"> |
| <span class="navbar-toggler-icon"></span> |
| </button> |
| |
| <div class="collapse navbar-collapse" id="navbarADP"> |
| <ul class="navbar-nav me-auto mb-2 mb-lg-0"> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" href="#" data-bs-toggle="dropdown" aria-expanded="false">About</a> |
| <ul class="dropdown-menu"> |
| <li><a class="dropdown-item" href="/team.html">About the team</a></li> |
| <li><a class="dropdown-item" href="/roundtable.html">The Infrastructure Roundtable</a></li> |
| <li><a class="dropdown-item" href="/blog/">The Infrastructure Blog</a></li> |
| </ul> |
| </li> |
| <li class="nav-item"> |
| <a class="nav-link" href="/policies.html">Policies</a> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" href="#" data-bs-toggle="dropdown" aria-expanded="false">Services and Tools</a> |
| <ul class="dropdown-menu"> |
| <li><a class="dropdown-item" href="/services.html">Services and Tools</a></li> |
| <li><a class="dropdown-item" href="/machines.html">Machines and Fingerprints</a></li> |
| <li><a class="dropdown-item" href="https://blocky.apache.org/">Blocky</a></li> |
| <li><a class="dropdown-item" href="https://app.datadoghq.com/account/login?next=%2Finfrastructure">DataDog</a></li> |
| <li><a class="dropdown-item" href="https://whimsy.apache.org/roster/committer/" target="_blank">Committer Search</a></li> |
| </ul> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" href="#" data-bs-toggle="dropdown" aria-expanded="false">Documentation</a> |
| <ul class="dropdown-menu"> |
| <li><a class="dropdown-item" href="/doc.html">Contribute</a></li> |
| <li><a class="dropdown-item" href="/infra-volunteer.html">Volunteer with Infra</a></li> |
| <li><a class="dropdown-item" href="/how-to-mirror.html">Become an ASF download mirror</a></li> |
| <li><a class="dropdown-item" href="/hosting-external-agent.html">Host a Jenkins or Buildbot agent</a></li> |
| |
| </ul> |
| </li> |
| <li class="nav-item"> |
| <a class="nav-link" href="/stats.html">Status</a> |
| </li> |
| <li class="nav-item"> |
| <a class="nav-link" href="/contact.html">Contact Us</a> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </nav> |
| |
| |
| <!-- page contents --> |
| <div id="contents"> |
| <div class="bg-white p-5 rounded"> |
| <div class="col-sm-8 mx-auto"> |
| <h1> |
| Getting started with Git |
| </h1> |
| <p>This document is a primer on using Git for an Apache Software Foundation project.</p> |
| <h2>Contents</h2> |
| <ul> |
| <li><a href="#repotypes">Repository types</a><ul> |
| <li><a href="#publicprivate">Public and private repositories</a></li> |
| </ul> |
| </li> |
| <li><a href="repocheckout">Repository checkout</a></li> |
| <li><a href="#committers">Committers: getting started</a></li> |
| <li><a href="#windowsusers">Windows users</a></li> |
| <li><a href="#lineendings">Line endings</a></li> |
| <li><a href="#trouble">Troubleshooting</a></li> |
| <li><a href="#further">Further reading</a></li> |
| </ul> |
| <h2 id="repotypes">Repository types<a class="headerlink" href="#repotypes" title="Permanent link">¶</a></h2> |
| |
| <p>There are two forms of Git repositories:</p> |
| <ol> |
| <li>Read-only mirrors hosted at <code>https://git.apache.org</code></li> |
| <li>Read/write repositories hosted at <code>https://gitbox.apache.org/repos/asf</code></li> |
| </ol> |
| <p>This document is chiefly about the read/write repositories.</p> |
| <h3 id="publicprivate">Public and private repositories<a class="headerlink" href="#publicprivate" title="Permanent link">¶</a></h3> |
| |
| <p>Projects can set up as many <strong>public repositories</strong> as their development work requires, using <a href="https://selfserve.apache.org/" target="_blank">SelfServe</a>. </p> |
| <p>Each project can also have a <strong>private repository</strong> space for working on sensitive issues such as:</p> |
| <ul> |
| <li>security patches</li> |
| <li>writing a draft of the project Board report when there is a section that will appear in a <code><private></code> tag</li> |
| <li>sharing credentials</li> |
| </ul> |
| <p>The private repository is <strong>not</strong> for uses such as project code development not related to a security issue.</p> |
| <p>See the <a href="project-repo-policy.html">Project Code Repository Policy</a> for further details.</p> |
| <p>Open a Jira ticket for Infra to request a private repository. </p> |
| <h2 id="repocheckout">Repository checkout<a class="headerlink" href="#repocheckout" title="Permanent link">¶</a></h2> |
| |
| <p>The repository URLs are all of the form:</p> |
| <div class="highlight"><pre><span></span><code>https://gitbox.apache.org/repos/asf/reponame.git |
| </code></pre></div> |
| |
| <h3>Cloning a repository</h3> |
| <ul> |
| <li><strong>Committers</strong>: <code>$ git clone https://gitbox.apache.org/repos/asf/reponame.git</code></li> |
| <li><strong>Non-Committers</strong>: <code>$ git clone http://gitbox.apache.org/repos/asf/reponame.git</code></li> |
| </ul> |
| <h2 id="committers">Committers: getting started<a class="headerlink" href="#committers" title="Permanent link">¶</a></h2> |
| |
| <p>Set up your name and email that Git will use when you make commits:</p> |
| <div class="highlight"><pre><span></span><code>$<span class="w"> </span>git<span class="w"> </span>config<span class="w"> </span>--global<span class="w"> </span>user.name<span class="w"> </span><span class="s2">"My Name Here"</span> |
| $<span class="w"> </span>git<span class="w"> </span>config<span class="w"> </span>--global<span class="w"> </span>user.email<span class="w"> </span>myusername@apache.org |
| </code></pre></div> |
| |
| <p>If you're a long-time GitHub user you can set these configuration variables on a per-repository basis:</p> |
| <div class="highlight"><pre><span></span><code>$<span class="w"> </span>git<span class="w"> </span>config<span class="w"> </span>user.name<span class="w"> </span><span class="s2">"My Name Here"</span> |
| $<span class="w"> </span>git<span class="w"> </span>config<span class="w"> </span>user.email<span class="w"> </span>myusername@apache.org |
| </code></pre></div> |
| |
| <p>You can also add your <code>apache.org</code> email address to your GitHub account so that the Apache mirrors on GitHub link to your Gravatar and user account.</p> |
| <p>To push to a repository you need to authenticate. More recent versions of Git prompt for a user name and password, and in some cases will cache the credentials in your operating system's default credential store.</p> |
| <p>On Mac OS X, you need to have <code>git-credential-osxkeychain</code> installed, and to set the following configuration:</p> |
| <div class="highlight"><pre><span></span><code>$<span class="w"> </span>git<span class="w"> </span>config<span class="w"> </span>--global<span class="w"> </span>credential.helper<span class="w"> </span>osxkeychain |
| </code></pre></div> |
| |
| <p>If you do not see an authentication prompt, you need to set up a <code>~/.netrc</code> file that contains your user credentials:</p> |
| <div class="highlight"><pre><span></span><code>$<span class="w"> </span><span class="o">(</span><span class="nb">umask</span><span class="w"> </span><span class="m">0277</span><span class="p">;</span><span class="w"> </span>cat<span class="w"> </span>>><span class="w"> </span>~/.netrc<span class="w"> </span><span class="s"><<EOF)</span> |
| <span class="s">machine gitbox.apache.org</span> |
| <span class="s">login username</span> |
| <span class="s">password mypassword</span> |
| <span class="s">EOF</span> |
| chmod<span class="w"> </span><span class="m">0600</span><span class="w"> </span>~/.netrc |
| </code></pre></div> |
| |
| <p>You can list your user name in the Git repository URL, but this requires that you provide your password for every fetch and push. You can simplify this step by cloning a URL like:</p> |
| <div class="highlight"><pre><span></span><code>$<span class="w"> </span>git<span class="w"> </span>clone<span class="w"> </span>https://username@gitbox.apache.org/repos/asf/reponame.git |
| </code></pre></div> |
| |
| <p>While it's <em>possible</em> to list your password in the URL, we discourage this practice as it leaves your password in plain text in the shell history.</p> |
| <h2 id="windowsusers">Windows users<a class="headerlink" href="#windowsusers" title="Permanent link">¶</a></h2> |
| |
| <p>You can use <code>git-gui</code> as part of the <code>msysgit</code> package.</p> |
| <p>Instead of setting up a <code>~/.netrc</code> file you need to:</p> |
| <ol> |
| <li>Set up a <code>%HOME%</code> environment pointing to <code>C:\Users\yourloginname\</code></li> |
| <li>Create a <code>_netrc</code> file in <code>%HOME%_netrc</code> with this text all on one line: <code>machine gitbox.apache.org login username password mypassword</code></li> |
| </ol> |
| <h2 id="lineendings">Line endings<a class="headerlink" href="#lineendings" title="Permanent link">¶</a></h2> |
| |
| <p>In general, you should normalize line endings in the Git repository and set them to be platform specific on checkout.</p> |
| <ul> |
| <li>The <code>msysgit</code> installer on <strong>Windows</strong> will prompt you to set the <code>core.autocrlf</code> setting to <code>true</code> by default. </li> |
| <li>On <strong>Mac OS X or Linux</strong>, use this setting: <code>$ git config --global core.autocrlf input</code></li> |
| </ul> |
| <p>Further details and attributes for handling line endings differently per file type are available at <a href="https://help.github.com/en/github/using-git/configuring-git-to-handle-line-endings" target="_blank">Configuring Git to handle line endings</a>.</p> |
| <h2 id="trouble">Troubleshooting<a class="headerlink" href="#trouble" title="Permanent link">¶</a></h2> |
| |
| <h4>no DAV locking</h4> |
| <p>If you get an error like this:</p> |
| <div class="highlight"><pre><span></span><code><span class="n">error</span><span class="o">:</span><span class="w"> </span><span class="n">no</span><span class="w"> </span><span class="n">DAV</span><span class="w"> </span><span class="n">locking</span><span class="w"> </span><span class="n">support</span><span class="w"> </span><span class="n">on</span><span class="w"> </span><span class="n">http</span><span class="o">://</span><span class="n">gitbox</span><span class="o">.</span><span class="na">apache</span><span class="o">.</span><span class="na">org</span><span class="sr">/repos/asf/reponame.git/</span> |
| <span class="n">fatal</span><span class="o">:</span><span class="w"> </span><span class="n">git</span><span class="o">-</span><span class="n">http</span><span class="o">-</span><span class="n">push</span><span class="w"> </span><span class="n">failed</span> |
| </code></pre></div> |
| |
| <p>It means that you're trying to push over <strong>HTTP</strong>, which is disabled. To fix this error change the remote repository URL to use <strong>HTTPS</strong>. You can edit the <code>.git/config</code> file to update the URL variable, or use:</p> |
| <div class="highlight"><pre><span></span><code>$<span class="w"> </span>git<span class="w"> </span>config<span class="w"> </span>remote.origin.url<span class="w"> </span>https://gitbox.apache.org/repos/asf/reponame.git |
| </code></pre></div> |
| |
| <h2 id="further">Further reading<a class="headerlink" href="#further" title="Permanent link">¶</a></h2> |
| |
| <ul> |
| <li><a href="https://lab.github.com/" target="_blank">GitHub Learning Lab</a></li> |
| <li><a href="https://github.github.com/training-kit/" target="_blank">Git Cheat Sheets</a></li> |
| <li><a href="github-roles.html">GitHub roles</a></li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <!-- footer --> |
| <div class="row"> |
| <div class="large-12 medium-12 columns"> |
| <p style="font-style: italic; font-size: 0.8rem; text-align: center;"> |
| Copyright 2024, <a href="https://www.apache.org/">The Apache Software Foundation</a>, Licensed under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br/> |
| Apache® and the Apache feather logo are trademarks of The Apache Software Foundation... |
| </p> |
| </div> |
| </div> |
| <script type="application/ecmascript" src="/js/bootstrap.bundle.min.js" integrity="sha384-OERcA2EqjJCMA+/3y+gxIOqMEjwtxJY7qPCqsdltbNJuaOe923+mo//f6V8Qbsw3"></script> </div> |
| </main> |
| <script>hljs.initHighlightingOnLoad();</script> |
| </body> |
| </html> |
