CINXE.COM

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> <meta name="robots" content="index,nofollow"> <title>Code/Git - Launchpad Help</title> <script type="text/javascript" src="/moin_static198/common/js/common.js"></script> <script type="text/javascript">  </script> <link rel="stylesheet" type="text/css" charset="utf-8" media="all" href="/moin_static198/lp20/css/common.css"> <link rel="stylesheet" type="text/css" charset="utf-8" media="screen" href="/moin_static198/lp20/css/screen.css"> <link rel="stylesheet" type="text/css" charset="utf-8" media="print" href="/moin_static198/lp20/css/print.css"> <link rel="stylesheet" type="text/css" charset="utf-8" media="projection" href="/moin_static198/lp20/css/projection.css">   <link rel="alternate" title="Launchpad Help: Code/Git" href="/Code/Git?diffs=1&show_att=1&action=rss_rc&unique=0&page=Code%2FGit&ddiffs=1" type="application/rss+xml"> <script type="text/javascript"> var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-12833497-4']); _gaq.push(['_trackPageview']); (function() { var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); })(); </script> <link rel="Start" href="/FrontPage"> <link rel="Alternate" title="Wiki Markup" href="/Code/Git?action=raw"> <link rel="Alternate" media="print" title="Print View" href="/Code/Git?action=print"> <link rel="Up" href="/Code"> <link rel="Search" href="/FindPage"> <link rel="Index" href="/TitleIndex"> <link rel="Glossary" href="/WordIndex"> <link rel="Help" href="/HelpOnFormatting"> </head> <body lang="en" dir="ltr"> <div id="header"> <h1> <a href="https://help.launchpad.net/" class="header-link"> <img src=' /moin_static198/lp20/img/logo.png ' /> launchpad help</a> </h1> <div id="finder"> <div class="fixbox"> <form id="searchform" method="get" action=""> <input type="hidden" name="action" value="fullsearch"> <input type="hidden" name="context" value="180"> <input id="searchinput" type="text" name="value" value="" size="20" onfocus="searchFocus(this)" onblur="searchBlur(this)" onkeyup="searchChange(this)" onchange="searchChange(this)" alt="Search"> </form> </div> <ul class="editbar"><li>Immutable Page</li><li><a class="nbinfo" href="/Code/Git?action=info" rel="nofollow">Info</a></li><li><a class="nbattachments" href="/Code/Git?action=AttachFile" rel="nofollow">Attachments</a></li><li> <form class="actionsmenu" method="GET" action="/Code/Git"> <div> <label>More Actions:</label> <select name="action" onchange="if ((this.selectedIndex != 0) && (this.options[this.selectedIndex].disabled == false)) { this.form.submit(); } this.selectedIndex = 0;"> <option value="raw">Raw Text</option> <option value="print">Print View</option> <option value="RenderAsDocbook">Render as Docbook</option> <option value="refresh">Delete Cache</option> <option value="show" disabled class="disabled">------------------------</option> <option value="SpellCheck">Check Spelling</option> <option value="LikePages">Like Pages</option> <option value="LocalSiteMap">Local Site Map</option> <option value="show" disabled class="disabled">------------------------</option> <option value="RenamePage" disabled class="disabled">Rename Page</option> <option value="DeletePage" disabled class="disabled">Delete Page</option> <option value="show" disabled class="disabled">------------------------</option> <option value="show" disabled class="disabled">Subscribe User</option> <option value="show" disabled class="disabled">------------------------</option> <option value="show" disabled class="disabled">Remove Spam</option> <option value="show" disabled class="disabled">Revert to this revision</option> <option value="PackagePages">Package Pages</option> <option value="SyncPages">Sync Pages</option> <option value="show" disabled class="disabled">------------------------</option> <option value="Load">Load</option> <option value="Save">Save</option> <option value="SlideShow">SlideShow</option> </select> <input type="submit" value="Do"> </div> <script type="text/javascript">  </script> </form> </li></ul> </div> </div> <div id="locationline"> </div> <div id="sepbar"> </div> <div id="login"> <div class="fl"> <h1 class="maintitle"> Code/Git </h1> </div> <div class="fr"> Not logged in - <a href="/?action=login">Log In / Register</a> </div> </div> <div id="pageline"><hr style="display:none;"></div> <div class="message"> </div> <div id="page" lang="en" dir="ltr"> <div dir="ltr" id="content" lang="en"> <a href="/FrontPage">Launchpad Help</a> > <a href="/Code">Code</a> > Git <div><table style="&quot; float:right; font-size: 0.9em; width:40%; background:#F1F1ED; margin: 0 0 1em 1em; &quot;"><tbody><tr> <td style="&quot; padding:0.5em; &quot;"><div class="table-of-contents">Contents<ol><li> <a href="#Overview">Overview</a></li><li> <a href="#What.27s_supported.3F">What's supported?</a></li><li> <a href="#What_will_be_supported.3F">What will be supported?</a></li><li> <a href="#Configuring_Git">Configuring Git</a></li><li> <a href="#Getting_code">Getting code</a></li><li> <a href="#Pushing_code">Pushing code</a><ol><li> <a href="#Permissions">Permissions</a></li></ol></li><li> <a href="#Repository_URLs">Repository URLs</a></li><li> <a href="#HTTPS_authentication">HTTPS authentication</a><ol><li> <a href="#Access_Tokens">Access Tokens</a></li><li> <a href="#Valid_scopes">Valid scopes</a></li><li> <a href="#Generating_access_tokens">Generating access tokens</a><ol><li> <a href="#Via_UI">Via UI</a></li><li> <a href="#Via_API">Via API</a></li></ol></li><li> <a href="#Using_access_tokens">Using access tokens</a></li><li> <a href="#Revoking_access_tokens">Revoking access tokens</a></li></ol></li><li> <a href="#Linking_to_bugs">Linking to bugs</a></li><li> <a href="#Mirroring_repositories_from_other_sites">Mirroring repositories from other sites</a></li><li> <a href="#Converting_from_Bazaar_to_Git">Converting from Bazaar to Git</a></li><li> <a href="#Deleting_a_Git_repository">Deleting a Git repository</a></li></ol></div></td> </tr> </tbody></table></div> <h1 id="Overview">Overview</h1> Launchpad supports hosting <a class="http" href="http://git-scm.com/">Git</a> repositories. This is distinct from the <a href="/Code/Imports">code import</a> facility that Launchpad has included for many years; it is now possible to host Git repositories on Launchpad directly. Git repositories use a somewhat different model from Bazaar branches: operations such as cloning happen at the level of a repository, but it is common for a single repository to contain many branches. This means that the Launchpad interface needs to be laid out somewhat differently to support that. <h1 id="What.27s_supported.3F">What's supported?</h1> This summary is up-to-date as of December 2022. Launchpad supports Git hosting. This means that you can: <ul><li>push Git repositories over SSH or HTTPS </li><li>clone repositories over git://, SSH, or HTTPS </li><li>see summary information on repositories and the branches they contain in the Launchpad web UI </li><li>follow links from the Launchpad web UI to a full-featured code browser </li><li>push and clone private repositories, if you have a commercial subscription to Launchpad </li><li>propose merges from one branch to another, including in a different repository, provided that they are against the same project or package </li><li>link Launchpad bugs to merge proposals </li><li>add <a href="/API/Webhooks">webhooks</a> to notify third-party services when repositories are changed </li><li>use <a href="/Packaging/SourceBuilds">recipes</a> to build packages in PPAs for code in Launchpad-hosted Git repositories </li><li>mirror repositories from other sites </li></ul> <h1 id="What_will_be_supported.3F">What will be supported?</h1> Launchpad's Bazaar support has grown many features over the years, and it will take some time to bring our Git support up to full parity with it. Here's an incomplete list of some of the features we expect to add: <ul><li>useful subscriptions (currently only attribute change notifications work, which are not usually very interesting in themselves) </li><li>RSS feeds </li><li>an integrated code browser </li></ul>Here's a short list of known bugs that you don't need to tell us about: <ul><li>the interface for registering merge proposals is very rough </li></ul> <h1 id="Configuring_Git">Configuring Git</h1> Git identifies repositories using URLs. Unlike Bazaar, there is no built-in abbreviation for repositories hosted on Launchpad, but it is very easy to add such a thing yourself. Edit <tt class="backtick">~/.gitconfig</tt> and add these lines, where <tt class="backtick">USER</tt> is your Launchpad username: <pre>[url "git+ssh://USER@git.launchpad.net/"] insteadof = lp:</pre>This allows you to type <tt class="backtick">git clone lp:REPOSITORY</tt> instead of <tt class="backtick">git clone git+ssh://git.launchpad.net/REPOSITORY</tt>. The rest of this documentation assumes that you have configured Git this way. You should check the <a href="/SSHFingerprints">fingerprint</a> of git.launchpad.net when prompted to do so by SSH. <h1 id="Getting_code">Getting code</h1> You can fetch the default repository for a project like this: <pre>$ git clone lp:PROJECT</pre>For example, <tt class="backtick">git clone lp:launchpad</tt> fetches Launchpad itself (or will once we've finished converting it to Git!). To keep your local clone up to date, run: <pre>$ git pull</pre> <h1 id="Pushing_code">Pushing code</h1> You can add a "remote" to your repository like this, if you own the project: <pre>$ git remote add origin lp:PROJECT</pre>Or like this (where <tt class="backtick">USER</tt> is your Launchpad username), if you do not own the project but want to contribute to it: <pre>$ git remote add origin lp:~USER/PROJECT</pre>Or to push a repository that isn't part of any Launchpad project or package, e.g. an ad-hoc experiment: <pre>$ git remote add origin lp:~USER/+git/REPOSITORY-NAME</pre>Now, you can push a branch using a command such as this: <pre>$ git push origin my-changes</pre> <h2 id="Permissions">Permissions</h2> By default, repository owners may create, push, force-push, or delete any branch or tag in their repositories, and nobody else may modify them in any way. Repository owners can use the "Manage permissions" page of a repository to change this by protecting branches or tags. By default, protecting a branch implicitly prevents repository owners from force-pushing to it or deleting it, while protecting a tag prevents repository owners from moving it. You can modify these default permission grants to be more restrictive (for example, you might prevent anyone from pushing to an archived branch), or to grant other permissions (for example, you might want to allow a contributor to push to certain branches in your repository without owning it). You may create rules that match a single branch or tag, or wildcard rules that match a pattern: for example, <tt class="backtick">*</tt> matches everything, while <tt class="backtick">stable/*</tt> matches <tt class="backtick">stable/1.0</tt> but not <tt class="backtick">master</tt>. The pattern is implemented using Python's <a class="https" href="https://docs.python.org/3/library/fnmatch.html#fnmatch.fnmatch">fnmatch</a>. Any owner of a repository can change its permissions, so restricting permissions for other repository owners is not a strict security barrier. However, you can use the "View activity" page of a repository to see what permission changes have been made. Launchpad works out the effective permissions that a user has on a protected branch or tag as follows: <ol type="1"><li>Take all the rules that match the branch or tag. </li><li>For each matching rule, select any grants whose grantee matches the user, as long as the same grantee has not already been seen in an earlier matching rule. (A user can be matched by more than one grantee: for example, they might be in multiple teams.) </li><li>If the user is an owner of the repository and there was no previous "Repository owner" grant, then add an implicit grant allowing them to create or push. </li><li>The effective permission set is the union of the permissions granted by all the selected grants. </li></ol> <h1 id="Repository_URLs">Repository URLs</h1> Every Git repository hosted on Launchpad has a full "canonical" URL of one of these forms (these are the versions you'd use in a web browser; you only need to change the scheme and host parts for the command-line Git client): <dl><dt>https://code.launchpad.net/~OWNER/PROJECT/+git/REPOSITORY</dt><dd>This identifies a repository for an upstream project. </dd><dt>https://code.launchpad.net/~OWNER/DISTRIBUTION/+source/SOURCE/+git/REPOSITORY</dt><dd>This identifies a repository for a source package in a distribution. </dd><dt>https://code.launchpad.net/~OWNER/+git/REPOSITORY</dt><dd>This identifies a "personal" repository with no particular connection to any project or package (like "+junk" in Launchpad's Bazaar code hosting). </dd></dl>These are unique, but can involve quite a lot of typing, and in most cases there's no need for more than one repository per owner and target (project or package). Launchpad therefore has the notion of "default repositories". A repository can be the default for a target, in which case it has one of these forms: <dl><dt>https://code.launchpad.net/PROJECT</dt><dd>This is the default repository for an upstream project. </dd><dt>https://code.launchpad.net/DISTRIBUTION/+source/SOURCE</dt><dd>This is the default repository for a source package in a distribution. </dd></dl>Or a repository can be a person's or a team's default for a target, in which case it has one of these forms: <dl><dt>https://code.launchpad.net/~OWNER/PROJECT</dt><dd>This is an owner's default repository for an upstream project. </dd><dt>https://code.launchpad.net/~OWNER/DISTRIBUTION/+source/SOURCE</dt><dd>This is an owner's default repository for a source package in a distribution. </dd></dl>We expect that projects hosting their code on Launchpad will normally have their primary repository set as the default for the project, and contributors will normally push to branches in owner-default repositories. The extra flexibility with named repositories allows for situations such as separate private repositories containing embargoed security fixes. <h1 id="HTTPS_authentication">HTTPS authentication</h1> <h2 id="Access_Tokens">Access Tokens</h2> To push repositories over HTTPS, or to clone or pull private repositories over HTTPS, you need to use access tokens. These are text strings generated by Launchpad that can be used as HTTP passwords for particular repositories, with scope limitations and optional expiry dates. You can generate access tokens for a particular repository - which will grant access to that particular repository, or for a project - which will grant access to all repositories within that project (accessible by the user that generated them). <h2 id="Valid_scopes">Valid scopes</h2> For use with the <tt class="backtick">git</tt> client, the relevant scopes are <tt class="backtick">repository:pull</tt> to allow cloning or pulling the repository, and <tt class="backtick">repository:push</tt> to allow pushing the repository; you may select either or both. There is also <tt class="backtick">repository:build_status</tt> which allows seeing and updating the build status for all commits in a repository. <h2 id="Generating_access_tokens">Generating access tokens</h2> <h3 id="Via_UI">Via UI</h3> To generate an access token for a repository or project: <ol type="1"><li>Navigate to it in the Launchpad web UI </li><li>Select "Manage access tokens" </li><li>Enter a description of the token </li><li>Select some scopes that the token should grant </li><li>[Optional] You may also set an expiry date for the token if you wish </li><li>Press "Create token" </li></ol>Launchpad will generate a token and show it to you: note that Launchpad only stores a hash of the token for verification and not the token itself, so you must make a copy of the token at this point as Launchpad will not be able to show it to you again. <h3 id="Via_API">Via API</h3> Alternatively, you can generate access tokens using the <a href="/API">Launchpad API</a>, as follows: <pre># The path argument should be the clone URL for your repository or project, without the # leading "https://git.launchpad.net/". For example, if you want to # generate a token for https://git.launchpad.net/~user/example-project, use # path="~user/example-project". >>> repository = lp.git_repositories.getByPath(path="...") # Generate a pull-only token: >>> repository.issueAccessToken(description="pull token", scopes=["repository:pull"]) # Generate a push-only token: >>> repository.issueAccessToken(description="push token", scopes=["repository:push"]) # Generate a token that can either pull or push: >>> repository.issueAccessToken(description="pull/push token", scopes=["repository:pull", "repository:push"])</pre>Similarly, to create a project access token: <pre>>>> project = lp.load("<name of project>") # Generate a token that can either pull or push: >>> project.issueAccessToken(description="pull/push token", scopes=["repository:pull", "repository:push"])</pre> <h2 id="Using_access_tokens">Using access tokens</h2> You can use access tokens as HTTPS passwords, in conjunction with your Launchpad username. For one-off testing you can just enter these when <tt class="backtick">git</tt> prompts you to do so. However, if you're using them more seriously then you will probably want to store them somewhere; for that, see the advice from "Pro Git" on <a class="https" href="https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage">credential storage</a>. <h2 id="Revoking_access_tokens">Revoking access tokens</h2> Tokens can be revoked in Launchpad's web UI by anyone that can see them listed, where a user can see a token listed if they are the direct or indirect (through team membership) owners of the token, or if they are the direct or indirect owners of the git repository/project. Owners of the git repository/project can see all its tokens. <h1 id="Linking_to_bugs">Linking to bugs</h1> Git-based merge proposals can be linked to Launchpad bugs. This can be done manually from the web UI for the merge proposal, but normally you should just mention the Launchpad bug in the commit message of one of the commits you want to merge. The required commit message text to link to bugs #XXX and #YYY looks like this: <pre>LP: #XXX, #YYY</pre>Technically, the commit message needs to match this regular expression, case-insensitively: <pre>/lp:\s+\#\d+(?:,\s*\#\d+)*/</pre> This is the same pattern used to match Launchpad bug references in <tt class="backtick">debian/changelog</tt> files in source packages.Bugs are not automatically closed when merge proposals land, because the policy for when that should happen varies from project to project: for example, projects often only close bugs when they make releases, or when their code is deployed to production sites. Users familiar with Bazaar on Launchpad should note that the model for Git bug linking is slightly different: bugs are linked to merge proposals rather than to individual branches. This difference is mainly because individual branches within a Git repository are often much more ephemeral than Bazaar branches. If you need a more advanced bug-handling workflow for your project, you can use a <a href="/API/Webhooks">webhook</a> to help. See <a class="https" href="https://git.launchpad.net/kicad-git-hook">kicad-git-hook</a> for an example contributed by a Launchpad user. <h1 id="Mirroring_repositories_from_other_sites">Mirroring repositories from other sites</h1> You can tell Launchpad to create a repository which is imported from some other site. There are two ways to set this up. <ol type="1"><li>This method is preferred in the common case of importing the upstream repository for a project. <ul><li>Go to the main page in Launchpad for a project you maintain, and follow the "Code" link under "Configuration options". </li><li>Set "Version control system" to "Git" if necessary. </li><li>Select "Import a Git repository hosted somewhere else". </li><li>Fill in the repository name (this should normally just be the project name). </li><li>Set the repository owner if necessary (defaults to you, can be any public team you participate in). </li><li>Fill in the URL of the remote repository. </li><li>Launchpad will create the repository, set it as the default for your project, and schedule an import. </li></ul></li><li>This method is useful for other cases, such as importing repositories that are not the primary upstream repository for a project. <ul><li>Go to the "<a class="https" href="https://code.launchpad.net/+code-imports/+new">Request a code import</a>" page. </li><li>Select "Git" for both the version control system and the target version control system. </li><li>Fill in the other details as above. </li><li>Launchpad will create the repository and schedule an import, but in this case it will not set it as the default for your project. </li></ul></li></ol>In either case, Launchpad will mirror the whole repository from the remote site, and will keep its copy up to date regularly. You won't be able to push directly to the imported repository on Launchpad, but you can create another repository in the same project and push branches to that, and even create merge proposals if you want (though you may have to tell the upstream maintainer about them separately!). You can create source package recipes or Snap packages based on branches in the imported repository. Please note that Launchpad can only mirror public repositories. <h1 id="Converting_from_Bazaar_to_Git">Converting from Bazaar to Git</h1> There <a class="https" href="https://www.google.com/search?{google:acceptedSuggestion}oq=convert&sourceid=chrome&client=ubuntu&channel=cs&ie=UTF-8&q=convert+from+bzr+to+git">are</a> <a class="https" href="https://astrofloyd.wordpress.com/2012/09/06/convert-bzr-to-git/">several</a> <a class="http" href="http://www.fusonic.net/en/blog/2013/03/26/migrating-from-bazaar-to-git/">useful</a> <a class="http" href="http://blog.timmattison.com/archives/2011/06/13/how-to-convert-from-bzr-to-git-on-debianubuntu/">recommendations</a> online for how to convert from Bazaar to Git. Here's one way that preserves tags and does a pretty good job for relatively simple Bazaar branches. <pre>$ cd /some/place # parent directory of Bazaar branch $ mkdir new-git-repo $ cd new-git-repo $ git init . $ bzr fast-export --export-marks=../marks.bzr ../old-bzr-branch | git fast-import --export-marks=../marks.git $ git checkout master</pre>Now the <tt class="backtick">new-git-repo</tt> directory is a Git repository with history equivalent to your old Bazaar branch. You should push it somewhere, and to ensure that everything is correct you should re-clone it locally to whatever final destination path you want to work in. If you have several different Bazaar branches that form part of the same project, or if your Bazaar branches constitute packaging for a project whose upstream is in revision control elsewhere, then you may well want to do a more careful conversion. For this, <a class="http" href="http://www.catb.org/~esr/reposurgeon/">reposurgeon</a> is an excellent tool: it gives you a language for describing the transformations you want to make to your input branches, so you can run the migration several times with different tweaks before deciding that the result is the one you want to publish to the world. Once you're ready to use Git by default for your project, you can configure this from <a class="https" href="https://launchpad.net/PROJECT/+configure-code">https://launchpad.net/PROJECT/+configure-code</a> (which is linked from the "Configuration Progress" section of the main project page on Launchpad). <h1 id="Deleting_a_Git_repository">Deleting a Git repository</h1> In order to delete a Git repository, you need to follow these steps: <ul><li>go to the project </li><li>scroll down to the "Code" section </li><li>click on repository listed as "lp:<your-repository-name>" </li><li>on the right hand side click on "Delete repository" </li><li>confirm the deletion on the next page </li></ul>As an alternative you can also use "lp-shell" to delete the repository: <pre>lp.load('path to repository').lp_delete()</pre></div>Code/Git (last edited 2023-10-19 13:59:58 by <a class="interwiki" href="https://launchpad.net/~jugmac00" title="jugmac00 @ 2001:67c:1560:8007::aac:c5c9[2001:67c:1560:8007::aac:c5c9]">jugmac00</a>) <div id="pagebottom"></div> </div> <div id="footer"> <a href="https://help.launchpad.net/Legal">Terms of use</a> | <a href="https://launchpad.net/feedback">Help improve Launchpad</a> | <a href="https://launchpad.net/faq">FAQ</a> | <a href="/RecentChanges">Recent Changes</a> <a rel="license" href="http://creativecommons.org/licenses/by/2.0/uk/"> Launchpad Help by <a xmlns:cc="http://creativecommons.org/ns#" href="https://canonical.com/" property="cc:attributionName" rel="cc:attributionURL">Canonical Ltd</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/2.0/uk/">Creative Commons Attribution 2.0 UK: England & Wales License</a>. <img alt="Creative Commons License" style="border-width:0;vertical-align:middle;" src="https://licensebuttons.net/l/by/2.0/uk/80x15.png" /></a> © 2004-2019 <a href="https://canonical.com/" target="_blank">Canonical Limited.</a> </div> </body> </html>