Revision 21 as of 2016-10-19 21:30:24

Clear message

The Ubuntu Server Team has devised a git-based workflow for merges. It relies on a set of tools written to assist in the process, but the underlying driver is a basic git-rebase process. This page will attempt to describe the tools used, and the general workflow, with an example or two. Finally, there will be some notes about corner-cases or caveats to the process that might need special-handling.

There are two aspects to the workflow: on the one had is a the importer logic, which relates to the construction of the repository(ies) in Launchpad for source package, and is documented in brief here mostly for transparency and documentation; on the other hand are tools for using the git repositories in Launchpad to do bugfixes and merges, which most likely the section of interest to developers.

NB: this page is a work in progress and no guarantees are asserted as to its correctness while it is being fleshed out.

Git configuration

Throughout this documentation, we will make reference to several git 'insteadof' shortcuts, which can be placed into .gitconfig as:

[url "git+ssh://"]
    insteadOf = ldusdp:
[url "git+ssh://"]
    insteadOf = lpusip:
[url "git+ssh://"]
    insteadOf = lpmep:

Important note: lpusip and lpusdp are used somewhat interchangeably on this page, to refer to the 'canonical' (little c) imported git tree. lpusip is used currently as a staging area while we work through bugs in the importer and the process documented here. Once we have accepted this tooling as the "default", we will move to lpusdp and lpusip will probably be decommisioned.

Git workflow for merging

Algorithm outline

  1. Obtain git tree.
  2. Deconstruct current Ubuntu delta into logical commits.
  3. Rebase delta onto latest Debian release.
  4. Build/test.
  5. Reconstruct debian/changelog for new version.
  6. Update metadata for new version.
  7. Upload.

Detailed workflow

This guide assumes we are attempting to merge the version of <source package name> in the latest Ubuntu series with the latest Debian unstable version. If that is not the case, you might need to pass different commitishes to usd-merge and/or specify the onto. See below for details.

  1. Obtain git tree.
    1. See if there is already an imported tree at

      1. If there is, check if it is current. This usually means checking rmadison and ensuring that both 'debian/sid' and 'ubuntu/<current development series>' are consistent with it. In the future, there will be a 'ubuntu/devel' reference that can be checked, and as long as 'debian/sid' and 'ubuntu/devel' are accurate, the tree can be treated as current. The eventually should not be necessary as we will run the importer in a cronjob.

        1. If it is, proceed to the next step.
        2. If it is not, send an e-mail to the Ubuntu Server list asking for it to be updated or import it locally (see the usd-import section). You should eventually get a reply with a reference to the imported tree.

      2. If there is not, send an e-mail to the Ubuntu Server list asking for it to be imported or import it locally (see the usd-import section). You should eventually get a reply with a reference to the imported tree.

    2. git clone -n lpusip:<source package name>

      1. Feel free to use other git configuration flags, etc. as desired, but this guide will only cover the case where there is on extra configuration.
      2. If you do not pass '-n', git clone will complain that: warning: remote HEAD refers to nonexistent ref, unable to checkout. This is because we don't use a master branch and git assumes it exists. It can be safely ignored. A goal is to modify the repository configuration so that this error is not issued, but it is harmless.

    3. git remote add lpme lpmep:<source package name>

      1. This simply adds a remote pointing to your user's Launchpad git repository for this source package.
      2. git fetch lpme

        1. This may not fetch any objects if the remote doesn't exist yet, but that's ok, because we want this reference for eventual pushing and submitting a Merge Request (MR).
  2. Deconstruct current Ubuntu delta into logical commits.
    1. usd-merge tag origin/ubuntu/<latest series>

      1. This will create a local 'debian/sid' branch that tracks 'origin/debian/sid'.
      2. This will create 3 tags (you might need to pass '-f' if the tags already exist).
        1. 'old/ubuntu': will point to the same commit as origin/ubuntu/<latest series> tip and represents the current state of Ubuntu for this source package. In other words, this tag points to a commit corresponding to the latest Ubuntu version and containing the complete Ubuntu delta.

        2. 'old/debian': will point to the commit that is a common ancestor of both origin/ubuntu/<latest series> tip and origin/debian/sid tip, in other words the commit corresponding to the version last merged from Debian.

        3. 'new/debian': will point to origin/debian/sid tip, in other words the commit corresponding to the version to be merged with and the latest version in Debian unstable.
      3. You may want to verify the tags (with git show <tag>) are pointing to the expected commits/versions.

    2. usd-merge reconstruct old/ubuntu

      1. In the importer algorithm, explained later, each imported version is a git-merge. If you were to directly rebase 'old/ubuntu' onto 'debian/sid', the merges would be replayed, which will typically fail.

      2. Instead, this will replay the current ubuntu delta back onto 'old/debian', but dropping the git-merge commits that are artifacts of the usd-import algorithm.

      3. The end result, which will be the checked-out if successful, is a sequence of git-cherry-picks of published Ubuntu versions after the 'old/debian' version that are not merges (but are otherwise identical to the sequence of commits in 'old/ubuntu'.

      4. This commit is tagged as 'reconstruct/<ubuntu version>'.

        1. Please note that our convention is to use '{reconstruct,deconstruct,logical}/<version>' (with standard dep14 substitutions). This allows us to store multiple tags associated with multiple versions for archival purposes.

    3. git rebase -i old/debian

      1. Interactively rebase the reconstructed Ubuntu delta and edit ('e' in the rebase options) each cherry-picked commit into its components.
        1. While we will try to cover as many cases as possible in this document (when final), the man git-rebase "INTERACTIVE MODE" section is probably still worth reviewing.

        2. In the editor provided by git-rebase, modify each 'p'/'pick' line to 'e'/'edit'.

        3. As the git-rebase process stops at each commit, run git reset HEAD^, which will unstage each commit.

        4. See what was previously in the commit at this point with git-diff. In particular, we are interested in what is indicated by 'debian/changelog' as being contained in this published Ubuntu version.

        5. Run git add -i (interactive add) to stage a commit for each change listed in the 'debian/changelog' diff.

        6. Run git commit to commit the staged changes, using the 'debian/changelog' entry as the commit message.

        7. Sometimes, there will be changes in a published release that are not mentioned in 'debian/changelog'. It is recommended to commit each of these as a new commit after those that are listed in 'debian/changelog', with an appropriate commit message, appending '[previously undocumented]'.
        8. The remaining changes should only be to 'debian/changelog' (the actual changelog entries) and 'debian/control' (VCS/maintainer modifications). This is verifiable by examining git diff -p and git diff.

          1. Commit all the 'debian/changelog' entries for this step with commit message 'changelog'.
          2. Commit any debian/control metadata (VCS, Maintainer) for this step with commit message 'update-metadata'.
        9. The result at the end of each rebase step is no modifications are lost/gained relative to the old commit (which no longer applies in the current state).
          1. At this point, git diff should report no unstaged changes. Run git rebase --continue and repeat the previous steps for the next published Ubuntu version.

      2. The end result of the above loop will be a sequence of smaller commits, one per 'debian/changelog' entry (with potentially additional commits for previously undocumented changes).
        1. The final commit will represent a broken-out history (viewable with git-log) for the latest Ubuntu version and no contentful differences to that Ubuntu version.

        2. This can be verified with git diff -p old/ubuntu.

    4. git tag deconstruct/<ubuntu version>

      1. Tag the final commit for easy reference and review.
    5. git rebase -i old/debian

      1. Interactively rebase the deconstructed Ubuntu delta and drop 'changelog' and 'update-metadata' changes, by simply dropping those lines from the rebase todo file.
      2. An additional goal in this step is to consolidate the delta, e.g. sometimes a change is added in one Ubuntu release and then removed in a subsequent Ubuntu release. The changes, in this case, should simply be dropped.
      3. These changes will be easily reproducible from this process and will lead to merge conflicts with the final rebase.
      4. The final commit will represent a consolidated broken-out history (viewable with git-log) for the latest Ubuntu version, without changes to 'debian/changelog' or to the metadata in 'debian/control'.

        1. This can be verified with git diff -p old/ubuntu which should indicate the only changes are in 'debian/changelog' and 'debian/control'.

    6. git tag logical/<ubuntu version>

      1. Tag this commit for easy reference and review.
  3. Rebase delta onto latest Debian release.
    1. git rebase -i new/debian

      1. Replay the logical delta onto the latest Debian release.
  4. Build/test.
    1. Explain sbuild / point to it.
  5. Reconstruct debian/changelog for new version.
    1. git merge-changelogs old/debian old/ubuntu new/debian

    2. git reconstruct-changelog new/debian

  6. Update metadata for new version.
    1. update-maintainer

  7. Consider some Cleanup and check open Bugs
    1. Go to<source package name>. There check if any open bugs are either:

      1. closed already but not updated yet => close them

      2. likely closed, but need verification => notify reporter

      3. would be reasonable to add on top of the merge now that the package is touched anyway => implement

    2. Check all you have listed as "remaining Changes" in your changelog and consider pushing as much as possible to Debian.
  8. Push and review.
    1. git checkout -b merge

      1. The MR will be based off this branch, feel free to name it something else.
    2. git push lpme merge old/debian new/debian old/ubuntu reconstruct/<ubuntu version> \

      • deconstruct/<ubuntu version> logical/<ubuntu version>

    3. Go to the Launchpad page of your just uploaded merge branch and propose for merging into the USD git project: ~<yourusername>/ubuntu/+source/<yourpackage>/+git/<yourpackage>/+ref/merge

      1. usually you just search for the package you want to upload and will find the related usd importer tree. For example ~usd-import-team/ubuntu/+source/<yourpackage>`

      2. As target use debian/sid or whatever you used to rebase on

      3. Discussions, new revisions and so on will be handled on that merges launchpad page. It is useful to add the path of the merge to a bug as you would add a debdiff.
  9. Upload (work in progress!)
    1. usd-merge commit ubuntu/<latest series>

    2. `git push lpusdp:<source package name>

      1. Presumes you have write rights to the USD git repository.

Tools: their usage, and where to get them


usage: usd-import [-h] [-o LP_OWNER] [-l LP_USER] [--no-push] [--force-push]
                  [--no-clean] [-v] [-d DIRECTORY] [-P PARENTFILE]

Update a launchpad git tree based upon the state of the Ubuntu and Debian

positional arguments:
  package               Which package to update in the git tree

optional arguments:
  -h, --help            show this help message and exit
  -o LP_OWNER, --lp-owner LP_OWNER
                        Which launchpad user's tree to update (default:
  -l LP_USER, --lp-user LP_USER
                        Specify the Launchpad user to use (default: <current username>)
  --no-push             Do not push to the remote (default: False)
  --force-push          Forcibly push all tags and branches from the import
                        (default: False)
  --no-clean            Do not clean the temporary directory (default: False)
  -v, --verbose         Increase verbosity (default: False)
  -d DIRECTORY, --directory DIRECTORY
                        Use git repository at specified location rather than a
                        temporary directory (implies --no-clean). Will create
                        the local repository if needed. (default: None)
                        File specifying parent-child relationship overrides
                        as: <pkgname> <child version> <parent1 version>
                        <parent2 version> with one override per line.
                        (default: None)

Available from Launchpad git repository.

The primary problem we are trying to solve is how to make merges consistent across the server team, and, ideally easy to review for sponsors/uploaders.

Robie Basak and others came up with a git-based workflow (documented broadly here and hopefully clarified on this page). This workflow 'just' uses git (the only addition to 'stock' git are a few commands (git-dsc-commit, git-merge-changelogs, git-reconstruct-changelog) from Launchpad git repository.)) to effectively rebase the ubuntu tip onto the latest debian tip. That presumes you spent the time yourself to create a repository with commits representing the current states of debian unstable and the ubuntu development release.

The goal for the importer is to have canonical (little c) location for such commits to live, per-package. Everyone can refer to commits and tags in that tree, and they will have well-defined semantics and share SHA1s.

A secondary problem was obtaining the 'complete' history for a given source package. This would allow a user to git-blame a give file and get useful data. So we extended the algorithm (that Robie designed) to be more flexible. After hitting many corner-cases during implementation, we scrapped our complicated algorithm that produced clean trees for a clean algorithm that produces complicated trees.

Feel free to skip the next section if you're not interested in the implementation.

Algorithmic discussion

In essence, the algorithm looks at Launchpad's publishing history for versions it hasn't seen before (which if an empty or no local repository is specified and you aren't cloning an existing repository will be all of them). For each such version, it uses pull-lp-source/pull-debian-source equivalents and git-dsc-commit to import them into the git repository. Technically it uses a lower-level command then a proper commit (git write-tree and `git commit-tree`), so that we can get the imported tree, examine it and find its parents and then commit it. The parents for an imported tree are at most 2:

  1. The last version imported into the same series/pocket, with some knowledge of how to establish a new series/pocket.
  2. The last debian/changelog entry (using debian/changelog from the just-imported tree) that was successfully imported.

We call these the 'publishing parent' and 'changelog parent' respectively. Now, if we can't find either of these, we will orphan the import and if we only find one, we'll use what we have. But the resulting tree looks like many git-merges, even where there are not ubuntu-merges. This is correct by the algorithm but can be confusing to the original git-rebase workflow, because rebase will try to replay the git-merges and that doesn't work. More on this later.

Local usage

While the intention is to use the lpusip/lpusdp repositories as the remotes for merge requests, it is also possible to run the importer fully locally and not push to a remote.

usd-import --no-push <srcpkgname> -d /path/to/repository/

This will run the import algorithm locally, which can take some time, leaving the repository in /path/to/repository, but not pushing to any remotes. By the nature of the importing algorithm, the SHAs of the commits in your local tree will match the commits of the lpusip/lpusdp trees. Note that the -d path should not exist and it must be provided as an absolute path.

Now that you have a local import, it's probably best to perform the merge steps in a separate clone, e.g.

$ git clone -n /path/to/repository/git mergewd

Now you can do all the merge steps described above in mergewd. That way if you mess up and need to start again, your import directory is still pristine.

Also, because you'll likely need the orig.tar.gz for the new (Debian) version, you will find that in /path/to/repository. Copy that or symlink it to the parent directory of mergewd so debuild or whatever you use can find it.


usage: git-dsc-commit [--tree-only] DSCFILE

Untars the version specified by the DSCFILE and commits it to a git repository.

optional arguments:
  --tree-only           Only call git-write-tree on the result.
                        git-commit-tree will need to be manually
                        invoked to commit the changes to the

Available from Launchpad git repository.


usage: git-reconstruct-changelog COMMITISH

Replays git commit messages starting after COMMITISH into debian/changelog.

Available from Launchpad git repository.



Runs dpkg-mergechangelogs on the debian/changelogs from the passed commitishs.

Available from Launchpad git repository.


usage: xgit

Either 'enters' or 'exits' an xgit-configured git repository. Such a repository
as a git/ and gitwd/ directory structure, where git/ is the GIT_DIR and gitwd/
is the GIT_WORK_TREE. This allows for easier git-dsc-commit invocation and
clarity on what is in the working tree and what is not.

Available from Launchpad git repository.


Usage: usd-clone [options] package [dir]
   clone package to dir

          --git     [default] use protocol git
          --http    use protocol http
          --https   use protocol https
     -v | --verbose be more verbose.

          --no-launchpad-user     do not prompt for launchpad user
     -l | --launchpad-user  USER  launchpad user is USER

Must provide package.

A simple helper script which does not rely on the lpusip/lpusdp insteadof definitions. Instead it configures a local repository with appropriate remotes and tracking branches.

Available from Launchpad git repository


usage: usd-merge tag|reconstruct|commit [-f] <commitish> [<onto>]

  tag: create old/ubuntu, old/debian and new/debian tags for
       the specified Ubuntu merge.
  reconstruct: break the specified Ubuntu merge into a
               sequence of non-git-merge-commits suitable
               for rebasing.
  commit: appropriately parent the executed merge to align
          with usd-import. Also possibly moves the reference
          of <commitish> if it is a head name.

  - <commitish> is a reference to a commit whose corresponding
    version is to be merged.
  - <onto> is a reference to a commit whose corresponding
     version to prepare to merge with. If not specified,
     debian/sid is used.

  -f indicates to overwrite existing tags, where applicable

Working tree must be clean.

A simple helper script entitled which takes a usd-clone'd tree and a commitish and attempts to give you a reconstructed sequence of linear commits that represent the same state as the commitish. It does this by using merge-base to figure out the common ancestor (it assumes onto is debian/sid but it also accepts a parameter) and then playing back the git history for commits between the merge-base and commitish. It then cherry-picks those tags from oldest to newest against the merge-base and does a quick sanity check that the resulting commit does not differ from the original commitish.

It tags that as reconstruct/<version> which may conflict with the git-based workflow some have been using previously. In that workflow, reconstruct/<version> is the broken-down sequence of changes including changelog and metadata, where each commit is a single change from the changelog. I have taken to now calling that pointer deconstruct/<version> because it's clever.

So you would break down reconstruct/<version> into its constituent changes (per debian/changelog for each version) and tag the resulting end-commit as deconstruct/<version>.

That can then be broken up by our workflow into a logical/<version> tag and then rebased onto debian/sid (or the specified onto).

Available from Launchpad git repository.


Already imported trees live, currently, at:

Currently, because once we feel confident in the utility and correctness of the importer, we'll move them to


All of this tooling is not meant to replace or reproduce any prior tools or works. And it is definitely not meant to replace a basic understanding of what a merge is and why they are necessary. The tooling is meant to make merges easier, but they are still not foolproof and require care and thought.