Merge ~racb/git-ubuntu:prepare-upload-adjustments into git-ubuntu:master

[Robie Basak]

Make Jenkins happy

[Server Team CI bot (server-team-bot)]

PASSED: Continuous integration, rev:7f25e4872b2d134925d3c6768be7ece34e24f112
https://jenkins.ubuntu.com/server/job/git-ubuntu-ci/63/
Executed test runs:
    SUCCESS: VM Setup
    SUCCESS: Build
    SUCCESS: VM Reset
    SUCCESS: Unit Tests
    IN_PROGRESS: Declarative: Post Actions

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/server/job/git-ubuntu-ci/63//rebuild

review: Approve (continuous-integration)

[Athos Ribeiro (athos-ribeiro)]

LGTM!

At first I wondered if it would be a good idea to verify the contents of the "headers" dict in "cli_printargs", but then I realized it is already being done in "push" (even though that is being done through calls to "assert" and therefore we do rely on __debug__ being set to True).

review: Approve

[Robie Basak (racb)]

> At first I wondered if it would be a good idea to verify the contents of the "headers" dict in "cli_printargs", but then I realized it is already being done in "push"

Right - it's more tedious to test from something closer to the CLI interface, so I tend to test the inner bits more directly.

> (even though that is being done through calls to "assert" and therefore we do rely on __debug__ being set to True).

I'm not sure we're on the same page here. What I mean above is that I'm testing the contents of the "headers" dict in prepare_upload_test.py using tests that test the behaviour of the prepare_upload.py::push(). assert statements from there are the usual pattern for pytest-based test suites and test suites are expected to always run with asserts enabled.

There are separate assert statements in the code itself in prepare_upload.py::push(), but these are there to state (and runtime verify when asserts are enabled) invariants that would help fail earlier and more helpfully if there is a bug somewhere. But I intend to test every actual case from the test suite in prepare_upload_test.py. If there's something you spotted that you think isn't being tested from there, I'd like to add it!

[Athos Ribeiro (athos-ribeiro)]

> I'm not sure we're on the same page here. What I mean above is that I'm testing the contents of the "headers" dict in prepare_upload_test.py using tests that test the behaviour of the prepare_upload.py::push(). assert statements from there are the usual pattern for pytest-based test suites and test suites are expected to always run with asserts enabled.

I was referring to the assert calls in `gitubuntu/prepare_upload.py`, as you mentioned later in your reply. I was just wondering why they are not explicitly raising exceptions instead. The comments in that file do justify them though:

> # However, we don't know of any actual case when this might happen, so
  # these are assertions rather than fully UX-compliant error paths.

> If there's something you spotted that you think isn't being tested from there, I'd like to add it!

The only thing that came to mind was the regular expression to parse the git URL. Although it is based on the one present in `https://git.launchpad.net/launchpad/tree/lib/lp/app/validators/name.py`, it is slightly different since it allows the username to start with one of the allowed special characters. Parametrizing that test to include other valid username examples could prevent mistakes in future changes to that regex. However, this looks simple enough and perhaps the effort is just not worth here.

This LGTM :)

1f99957... by Lena Voytek on 2022-05-13

Updates for inclusive naming

Edit filenames, variables, and comments to match inclusive naming
standards. The user experience will remain the same with this
update. However, when allowing and denying specific packages,
additions must be placed in source-package-allowlist.txt and
source-package-denylist.txt instead of source-package-whitelist.txt
and source-package-blacklist.txt.

Signed-off-by: Lena Voytek <email address hidden>

ef3b3a9... by Robie Basak on 2022-05-20

Merge remote-tracking branch 'lvoytek/master'

57e5776... by Robie Basak on 2022-05-20

Update maintainer email address

<email address hidden> no longer exists. Use
<email address hidden> instead.

002e452... by Robie Basak on 2022-05-20

Update email address to request an import

This is for the message printed when a repository is not found on "git
ubuntu clone".

Since <email address hidden> no longer exists, we'll use
<email address hidden> instead.

2f0e855... by Robie Basak on 2022-05-20

Update email address default used in tests

Since <email address hidden> no longer exists, we'll use
<email address hidden> instead. This shouldn't affect
production code since the repo_builder and source_builder modules are
only used in tests.

5aad111... by Robie Basak on 2022-05-20

Update default bot account name

usd-importer-bot is now renamed to git-ubuntu-bot as part of catching up
the project rename to git-ubuntu.

5b0868f... by Sergio Durigan Junior on 2022-06-16

Accept ref names containing plus sign

Currently, if the ref name contains a plus sign, git ubuntu will fail
due to the following assertion error:

Traceback (most recent call last):
  File "/snap/git-ubuntu/891/usr/bin/git-ubuntu", line 11, in <module>
    load_entry_point('gitubuntu==1.0', 'console_scripts', 'git-ubuntu')()
  File "/snap/git-ubuntu/891/usr/lib/python3/dist-packages/gitubuntu/__main__.py", line 270, in main
    sys.exit(args.func(args))
  File "/snap/git-ubuntu/891/usr/lib/python3/dist-packages/gitubuntu/prepare_upload.py", line 170, in cli_printargs
    headers = push(
  File "/snap/git-ubuntu/891/usr/lib/python3/dist-packages/gitubuntu/prepare_upload.py", line 118, in push
    assert gitubuntu.importer.VCS_GIT_REF_VALIDATION.fullmatch(ref.name)
AssertionError

However, branch names (which compose ref names) are allowed to contain
the plus sign. This commit expands the VCS_GIT_REF_VALIDATION regexp
to accept that.

FWIW, I triggered this assertion when I named my branch after the
Debian release I was merging (for the net-snmp package):

  merge-5.9.1+dfsg-4-kinetic

f5dc43c... by Robie Basak on 2022-06-16

Clean up get_head_versions()

This method had no tests, and returning a pygit2.Branch object made it
harder to supply test data to other functions that accept data in the
structure returned by this method.

In practice, callers only need the version, commit time and commit hash
of each branch head, so return only exactly this, and adjust all
callers. This should not change any behaviour.

We also adjust and fill out the docstring.

A unit test will follow in a subsequent change. It can't be added here
without fixing a bug first.

b2f98c1... by Robie Basak on 2022-06-16

GitUbuntuSourceInformation: dependency injection

Add dependency injection to GitUbuntuSourceInformation. This allows the
creation of this object in tests such that we can mock a
launchpadlib.launchpad.Launchpad object.

a11bfa8... by Robie Basak on 2022-06-16

launchpad_versions_published_after: refactor call

We don't need to set args and then call with **args, given that is all
we do with it. Instead, just call self.archive.getPublishedSources()
with keyword arguments directly.

9addaa0... by Robie Basak on 2022-06-16

launchpad_versions_published_after: drop return

This return statement is redundant since it's at the end of the method
anyway.

535dca8... by Robie Basak on 2022-06-16

Use date_created to determine head versions

It's incorrect to use date_published to determine head versions that
will be used to match against Launchpad publications, since we use
date_created at commit creation time. We should be using date_created
consistently instead.

Not doing so means that we often (always?) fail to find a matching
Launchpad publication that is already imported and end up redundantly
reimporting everything from the beginning of time. This is terrible for
performance.

More details on date_created vs. date_published here:
https://irclogs.ubuntu.com/2020/04/16/%23launchpad.html#t13:45

This change is difficult to test right here. Further refactoring follows
in subsequent changes and a test is added later.

LP: #1979650

0b8cc0b... by Robie Basak on 2022-06-16

Rewrite launchpad_versions_published_after

The logic in this method can be simplified significantly with a rewrite.
To mitigate any regression, a parametrized unit test is added with the
expected behaviour thought out from the importer spec.

There is still an inefficiency present here. In theory we could skip
importing pocket copies if the branch corresponding to a pocket is
up-to-date. However, currently the algorithm only matches against the
exact date_created attribute of the Launchpad publication object against
which a particular version was first imported. To ensure that branches
are updated if any new pocket copies have occurred, we must "replay"
them all through the importer. Therefore there is potential here for a
future performance improvement.

284beb9... by Robie Basak on 2022-06-16

Add unit test for get_head_info()

Now that get_head_info() returns what we expect, we can add a unit test
for it now.

2133870... by Robie Basak on 2022-06-23

Refactor _head_version_is_equal

Add a docstring, refactor the code to make it more readable, and rename
the method to match its definition better.

This should not result in any functional change.

06f0eca... by Robie Basak on 2022-06-24

More project renames

This is a followup to commits 57e5776, 002e452, 2f0e855 and 5aad111 with
further cleanups around the project rename from usd-importer to
git-ubuntu and the move to the <email address hidden>
mailing list. Thanks to Bryce for spotting some of the remaining pieces.

Where code is no longer used at all, or docs are completely out-of-date,
I've removed it instead of renaming the relevant bits. I've not worried
too much about fixing docs that I've touched if there's some value to
them staying, as that's a bit of a rabbit hole and I'd prefer to make
incremental progress.

0e3ca5f... by Robie Basak on 2022-06-24

submit: default to ~canonical-server-reporter

On the Canonical Server Team, we have been using ~canonical-server in
its own review slot for the sole purpose of gathering all reviews we're
interested in tracking together on this team's +activereviews page.

A problem with this is that we all belong to this team, so when a person
does a review, they sometimes accidentally "grab" that slot, so it
appears as their name rather than the team's, and thus disappears from
the report.

One way around this is to use a separate team that none of us actually
belong to. This way we can't "grab" that slot.

This changes the default team to this new ~canonical-server-reporter
team to help those who use the "git ubuntu submit" command.

4d497a7... by Robie Basak on 2022-07-01

Add comment on missing observability

This should help locate the older emailing code should it be needed in
the future.

c8216a7... by Robie Basak on 2022-07-01

Add test to accept refs that contain '+'

ab3351a... by Robie Basak on 2022-07-01

Improve documentation on validation constants

This should hopefully do a better job of signposting anyone who wants to
change the constants to better understand the implications of doing so.

7c524e6... by Robie Basak on 2022-08-03

importer: flip sense of push arguments

Instead of passing around an inverse boolean "no_push" argument, pass
the more natural "push" instead.

This should make no functional change, but prepares us to invert the CLI
argument since after that future change passing around an inverse
boolean will make even less sense.

7f3a586... by Robie Basak on 2022-08-03

importer: flip CLI argument default to not push

git ubuntu import has two uses: 1) it's run by the importer service
workers, which should push by default; 2) it's run by users, for whom it
doesn't generally make sense to push by default.

Since it's easy for importer service workers to specify an option by
automation, we flip the default of the CLI to explicitly require --push
if you want to push. This makes it safer and easier to explain to users
how to use the import command locally.

The importer service worker then adds --push unconditionally.

This makes the "implied no push" behaviour of certain options redundant,
so those are removed.

0901740... by Robie Basak on 2022-08-03

scriptutils: remove pool_map_import_srcpkg()

This function is no longer used from anywhere.

4a01d97... by Robie Basak on 2022-08-03

importer-service-worker: add --no-push argument

Asking the worker for --no-push enables a deeper dry run for performance
testing purposes. Unlike the behaviour of "git ubuntu import", "push
mode" is the default here because normally when one sets up the importer
service, it would be surprising behaviour not to do this, and this is
the only use case for this command.

ab5d7ad... by Robie Basak on 2022-08-03

Move import_srcpkg() to importer_service_worker.py

This function is only used from here, so there's no need for it to be in
a different module.

8681418... by Robie Basak on 2022-08-04

_main_with_repo: simplify if statement

Since the normal operation is to push, and straight after that we
"return 0", it's simpler to immediately "return 0" if we don't want to
push. This stops the usual code path being pushed "to the right", and
makes it easier to follow the logic.

This should not result in a functional change.

f9a91d9... by Robie Basak on 2022-08-09

Add changelog date override for gmsh

36eef3f... by Robie Basak on 2022-08-23

prepare-upload: add test for ssh:// URL rewrites

According to LP 1942985, this is another case where a rewrite is
expected.

695a4d4... by Robie Basak on 2022-08-23

prepare-upload: handle ssh:// rewrites

According to LP 1942985, this is another case where a URL rewrite is
expected.

Unmerged commits

695a4d4... by Robie Basak on 2022-08-23

prepare-upload: handle ssh:// rewrites

According to LP 1942985, this is another case where a URL rewrite is
expected.

36eef3f... by Robie Basak on 2022-08-23

prepare-upload: add test for ssh:// URL rewrites

According to LP 1942985, this is another case where a rewrite is
expected.

cc48a7f... by Robie Basak on 2022-01-07

prepare-upload: output invalid option on failure

If "git ubuntu prepare-upload args" fails for whatever reason, we don't
want dpkg-buildpackage or similar to proceed if invoked using
"dpkg-buildpackage $(git ubuntu prepare-upload args)" as this will
silently hide the error. Instead, we can output an invalid option
"--git-ubuntu-prepare-upload-args-failed" which should cause
dpkg-buildpackage to fail, and hopefully lead the user to find the cause
in stderr from the failure in our command.

This change implments this new behaviour.

LP: #1942865

d8750f1... by Robie Basak on 2022-01-07

prepare-upload: test for invalid option on failure

If "git ubuntu prepare-upload args" fails for whatever reason, we don't
want dpkg-buildpackage or similar to proceed if invoked using
"dpkg-buildpackage $(git ubuntu prepare-upload args)" as this will
silently hide the error. Instead, we can output an invalid option
"--git-ubuntu-prepare-upload-args-failed" which should cause
dpkg-buildpackage to fail, and hopefully lead the user to find the cause
in stderr from the failure in our command.

This change adds the test for this behaviour, prior to implementation.

3c5c8c7... by Robie Basak on 2022-01-07

prepare-upload: rewrite LP git+ssh:// URLs

Automatically supply the corresponding https:// LP URL for the rich
history changes file headers if a git+ssh:// LP URL is used.

LP: #1942985

76824a3... by Robie Basak on 2022-01-07

prepare-upload: refactor header data handling

Explicitly pull out the three header data items into their own named
variables to avoid confusion.

dfa0998... by Robie Basak on 2022-01-07

prepare-upload: add test for git+ssh:// rewrite

Identified in LP: #1942985: if a user has a git+ssh:// LP URL, we should
automatically rewrite it to the https:// one.

This is the test for this, which is expected to fail because it isn't
fixed yet.

8fb8e5a... by Robie Basak on 2022-01-07

Fix typos in test docstrings

ab5d7ad... by Robie Basak on 2022-08-03

Move import_srcpkg() to importer_service_worker.py

This function is only used from here, so there's no need for it to be in
a different module.

4a01d97... by Robie Basak on 2022-08-03

importer-service-worker: add --no-push argument

Asking the worker for --no-push enables a deeper dry run for performance
testing purposes. Unlike the behaviour of "git ubuntu import", "push
mode" is the default here because normally when one sets up the importer
service, it would be surprising behaviour not to do this, and this is
the only use case for this command.

diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 0000000..ff10689
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,117 @@
+<<<<<<< doc/README.md
+=======
+## Running the git-ubuntu importer ##
+This just covers how to run [`git ubuntu import`](https://code.launchpad.net/git-ubuntu).
+
+## Getting via snap ##
+The preferred installation method is to install via snap:
+
+1. install the snap
+
+        $ snap install --classic git-ubuntu
+
+## [Alternate:]  Getting via git ##
+Less well tested, but in theory this should work as well.
+
+1. Get `git-ubuntu` from git
+
+        $ git clone git://git.launchpad.net/git-ubuntu git-ubuntu
+or
+
+        $ git clone https://git.launchpad.net/git-ubuntu git-ubuntu
+or
+
+        $ git clone ssh://git.launchpad.net/git-ubuntu git-ubuntu
+ 
+
+2. Put it in your PATH
+
+        $ PATH="$PWD/git-ubuntu/bin:$PATH"
+
+3. Get necessary dependencies
+
+        $ sudo apt update -qy
+
+        $ deps="dpkg-dev git-buildpackage python3-argcomplete \
+          python3-lazr.restfulclient python3-debian python3-distro-info \
+          python3-launchpadlib python3-pygit2 python3-ubuntutools \
+          python3-cachetools python3-pkg-resources python3-pytest \
+          python3-petname quilt"
+
+        $ sudo apt install -qy ${deps}
+
+
+## Running ##
+
+ * For local usage
+
+   `git ubuntu import` will push to launchpad git by default.  If you just want to get a git repo locally of a given package, then:
+
+        $ mkdir ${HOME}/Imports
+        $ PKG=uvtool
+        $ git ubuntu import -v --no-push --directory=${HOME}/Imports/$PKG $PKG
+
+ * As member of [git-ubuntu-import](https://launchpad.net/~git-ubuntu-import) for official publishing.
+
+        $ PKG=uvtool
+        $ LP_USER=smoser  # your launchpad user name if different from $USER
+        $ git ubuntu import -v --directory=$PKG --lp-user=$LP_USER $PKG
+
+## Shell completion (bash) ##
+
+ * `git-ubuntu` will autocomplete by default if global argcomplete has
+   been enabled
+   (https://github.com/kislyuk/argcomplete#activating-global-completion)
+   or specify
+
+   eval "$(register-python-argcomplete git-ubuntu)"
+
+   The snap version does this by default.
+
+ * `git ubuntu` autocompletion is a little more challenging. To enable
+   it, add the following to your .bashrc or similar:
+
+   if [ -f /path/to/git-ubuntu/doc/gitubuntu-completion.sh ]; then
+      . /path/to/git-ubuntu/doc/gitubuntu-completion.sh
+   fi
+
+   For the snap version, this would look like:
+
+   if [ -f /snap/git-ubuntu/current/doc/gitubuntu-completion.sh ]; then
+      . /snap/git-ubuntu/current/doc/gitubuntu-completion.sh
+   fi
+
+## View Output ##
+If you did a local checkout with `--directory=./$PKG` then you'll have a git repository in `./$PKG/git`.
+
+    $ cd $PKG
+    $ git branch 
+    ubuntu/saucy
+    ubuntu/saucy-proposed
+    ubuntu/trusty
+    ubuntu/trusty-proposed
+    ubuntu/utopic
+    ubuntu/utopic-proposed
+    ubuntu/vivid
+    ubuntu/vivid-proposed
+    ubuntu/wily
+    ubuntu/xenial
+    ubuntu/yakkety
+
+If you did `--lp-owner=git-ubuntu-import`, then your repo should be
+listed in web view at [https://code.launchpad.net/~git-ubuntu-import/+git].  And it should be able to be cloned with:
+
+    $ git clone https://git.launchpad.net/~git-ubuntu-import/ubuntu/+source/$PKG
+or
+
+    $ git clone lp:~git-ubuntu-import/ubuntu/+source/$PKG
+or
+
+    $ git ubuntu clone $PKG
+
+
+## Links ##
+ * [GitWorkflow Wiki page](https://wiki.ubuntu.com/UbuntuDevelopment/Merging/GitWorkflow)
+ * [Launchpad git for git-ubuntu](https://code.launchpad.net/git-ubuntu)
+ * [Git view of git-ubuntu](https://git.launchpad.net/git-ubuntu)
+>>>>>>> doc/README.md
diff --git a/doc/SPECIFICATION b/doc/SPECIFICATION
new file mode 100644
index 0000000..21cd184
--- /dev/null
+++ b/doc/SPECIFICATION
@@ -0,0 +1,167 @@
+<<<<<<< doc/SPECIFICATION
+=======
+Specification
+
+git URL shortcuts used (add these to ~/.gitconfig or expand them
+manually yourself):
+
+[url "ssh://<LPID>@git.launchpad.net/~<LPID>/ubuntu/+source/"]
+    insteadof = lpmep:
+
+Definitions: "old debian", "old ubuntu", "new debian", "new ubuntu" are
+as understood. Make sure that "old debian" is really the last common
+ancestor of "old ubuntu" and "new debian". Determining this is
+especially prone to error if Ubuntu imported new upstream versions since
+it diverged from Debian. If this is wrong, then pain will result.
+
+By "merge" we always mean an "Ubuntu merge", which is in git terms
+really a rebase. No actual git merge takes place in this entire
+workflow.
+
+No trees in this workflow ever have quilt patches applied. All commits
+are with quilt fully popped and no .pc directory. Changes to quilt
+patches are seen in debian/patches/* only.
+
+Common git references expected (T for tag, B for branch):
+
+Things that will be imported by a sponsor or the importer (available
+from: lpusip:<package>; ask a sponsor if missing):
+
+* T import/<version> and T upload/<version>
+  * Logically this is the tree corresponding to a particular tag;
+    history is secondary.
+  * The tree is identical to corresponding source package version in the
+    archive.
+  * For T import/<version>: imported from the archive and pushed to
+    ~git-ubuntu-import as an authoritative source.
+  * For T upload/<version>: pushed to ~ubuntu-server-dev by an uploader
+    to record exactly what was uploaded.
+  * Pushing to ~ubuntu-server-dev is restricted to uploaders.
+  * The parent commit should be the previous version import or upload
+    tag where available. An orphan commit is acceptable in the
+    exceptional case that this is not possible.
+
+* B ubuntu/devel
+  * Logically this is our moving reference for what is currently in the
+    Ubuntu development release.
+  * In ~ubuntu-server-dev, this must always point to something also
+    tagged as import/<version> or upload/<version>.
+  * Pushing to ~ubuntu-server-dev is restricted to uploaders.
+  * This branch will be rebased to new Debian imports during Ubuntu
+    "merges" (but tags will be left behind).
+
+Things that should be made available to a sponsor when submitting a
+merge for upload (push to: lpmep:<package>):
+
+* T logical/<old ubuntu>
+  * Logically, this is a patchset
+    ({import,upload}/<old debian>..logical/<old ubuntu>).
+  * Breakdown of previous Ubuntu delta.
+  * Must be based on an official import/<old debian> or upload/<old debian>
+    tag ("official" means from ~ubuntu-server-dev).
+  * One commit per logical change over the entire Ubuntu delta.
+  * Churn squashed.
+  * No upstream changes (so only changes in debian/*).
+  * No changes to debian/changelog.
+  * No "update-maintainer" or "Vcs-*" or other meta changes.
+  * To get to this, you will probably start from reconstruct/<old ubuntu>,
+    described below.
+  * Coherence checks:
+    - Identical to the corresponding import/<version> except for:
+      + Meta changes (update-maintainer, Vcs-*) in debian/control.
+      + Anything not in debian/*, which should be unchanged
+	(exceptionally this happens when new upstream versions were
+	imported ahead of Debian).
+      + debian/changelog, which should be unchanged.
+    - No line should be touched twice, except where separate logical
+      changes need to touch the same line.
+  * Providing this makes it easy for the sponsor to check a proposed
+    merge:
+    1. Check correctness of this tag against the previous Ubuntu delta
+       (perform the above checks and use "git log -p" to make
+       sure each logical commit describes only its own changes).
+    2. Ensure that every commit here is accounted for in the proposed
+       merge.
+
+* B merge
+  * Proposed merge for upload.
+  * Based on import/<new debian> or upload/<new debian>.
+  * One commit per logical change; no changes to debian/changelog in
+    those commits.
+  * One commit for each of merge-changelogs, reconstruct-changelog, any
+    changelog tweaks and ubuntu-meta (or update-maintainer as you wish).
+  * debian/changelog should be "released" with the version string
+    matching the proposed upload version and targeting the correct
+    pocket.
+  * Add commits to the end of this branch in response to reviewer
+    comments.
+  * If agreed with your sponsor that for the changes requested a new
+    rebased merge branch will be easier to manage than adding commits to
+    the end, then do this instead. Rebase the original "merge" branch.
+    To keep history, if you wish tag the old one "merge.v1". You may
+    also rebase like this as you wish during preparation before
+    presenting this branch for review.
+
+Things you may want to make available to reviewers so that they can
+check your process (push to: lpmep:<package>), for which we have
+standardised names:
+
+* T reconstruct/<old ubuntu>
+  * Logically, this is a patchset
+    ({import,upload}/<old debian>..reconstruct/<old ubuntu>).
+  * Based on import/<old debian>. For each Ubuntu upload since then:
+    * One commit to pull in a new upstream if there is one (rare). This
+      must not contain any changes to debian/.
+    * One commit per logical change.
+    * One commit for changelog.
+    * One commit for any ubuntu-meta/update-maintainer change (usually
+      only in merge uploads).
+  * Drop non-logical commits from this tip and rebase to squash and
+    split to derive the logical/<old ubuntu> tag.
+
+* T merge.v1, merge.v2, etc.
+  * The old state of each merge branch before you rebased it. Only
+    useful if you rebased during your merge. If done after your initial
+    review request, please only do this with agreement of your sponsor,
+    since it causes your sponsor more review time.
+
+Merge proposal to make in Launchpad:
+
+lpmep:<package> merge → lpusdp:<package> ubuntu/devel
+
+After review:
+
+If adding commits in response to reveiwer comments, just push again to
+lpmep:<package> merge.
+
+If (exceptionally) rebasing in response to reviewer comments:
+  1. Tag the old branch "merge.v1" (or v2, v3 etc. for future iterations)
+  2. Rebase the "merge" branch as required
+  3. Push to lpmep:<package>:
+     a) The new "v" tag from above.
+     b) The merge branch (force will be required).
+
+For "traditional" sponsors:
+
+git can easily generate the traditional debdiffs that you normally
+review. Assuming you have appropriate remote tracking branches:
+
+  * For Ubuntu → Ubuntu, "git diff lpusdp/ubuntu/devel sponsoree/merge"
+  * For Debian → Ubuntu, "git diff lpusdp/debian/sid sponsoree/merge"
+
+Or you can ask the sponsoree to generate these for you.
+
+To upload a reviewed merge (for the sponsor):
+
+(Sponsors: you can just ignore these instructions and upload the
+traditional way if you like. But sponsorees cannot push to our VCS and
+you can, so it would be nice if you could push this please, so a future
+merger doesn't have to reconstruct the lost information).
+
+1. Upload using dput as usual.
+2. Tag the merge branch "upload/<version>" (replace ':' and '~' with '_'
+   to meet git's naming requirements). A lightweight tag is fine, or
+   go ahead and annotate if you want to include any extra notes.
+3. Force push the merge branch to lpusdp:<package> ubuntu/devel.
+4. Push the "upload/<version>" tag to lpusdp:<package>.
+>>>>>>> doc/SPECIFICATION
diff --git a/doc/release-process.md b/doc/release-process.md
new file mode 100644
index 0000000..524736e
--- /dev/null
+++ b/doc/release-process.md
@@ -0,0 +1,264 @@
+<<<<<<< doc/release-process.md
+=======
+Release Process
+===============
+
+1.  Set the new version number
+------------------------------
+
+See gitubuntu/version.py for the current version number.
+
+  $ export LAST_RELEASE=$(cat gitubuntu/version.py | cut -d\' -f2)
+  $ echo "${LAST_RELEASE}"
+
+Git Ubuntu's version numbers follow the common MAJOR.MINOR.PATCH and
+MAJOR.MINOR.PATCH-rcN patterns, where for this project these are
+interpreted as follows:
+
+  - MAJOR is updated for API breaking changes such as alterations in
+    importer hash ABI stability.  As a special rule, MAJOR=0 indicates
+    no stability guarantees.  Notably, changes in MAJOR version are not
+    guaranteed to be forward or backward compatible with earlier MAJOR
+    versions.
+
+  - MINOR is incremented for feature-level changes that may alter how
+    the git ubuntu frontends behave, including breaking changes in how
+    git ubuntu subcommands and their parameters work.  The importer API,
+    however, is intended to be backward compatible from one MINOR
+    version to the next, with no breaking changes.
+
+  - PATCH is incremented for bug fixes and routine feature additions
+    that introduce no compatibility issues for either the backend
+    importer or the frontend client.  In particular, new commands and
+    parameters may be introduced, but existing ones will not be changed
+    or removed.
+
+  - rcN indicates a release candidate, using a sequential numbering for
+    'N'.
+
+Define the new version for the release:
+
+  $ export VERSION="<MAJOR>.<MINOR>.<PATCH>"
+
+Or, for a release candidate:
+
+  $ export VERSION="<MAJOR>.<MINOR>.<PATCH>-rcN"
+
+Set it in the git repo:
+
+  $ git checkout -b ${VERSION}-release
+  $ echo "VERSION = '${VERSION}'" > gitubuntu/version.py
+  $ git commit gitubuntu/version.py  -m "version: bump to ${VERSION}"
+  $ git tag --annotate -m "${VERSION} Release" ${VERSION}
+
+The annotated tag is necessary, because the snap build mechanisms
+determine the version to set in the snap based on it.
+
+
+2.  Draft release announcement
+------------------------------
+
+The release announcement generally summarizes the major changes in the
+release, and (where possible) identifies the bug fixes included in it.
+Some examples of past release announcements:
+
+  - 0.2.1: https://lists.ubuntu.com/archives/ubuntu-server/2017-September/007594.html
+  - 0.3.0: https://lists.ubuntu.com/archives/ubuntu-server/2017-October/007598.html
+  - 0.4.0: https://lists.ubuntu.com/archives/ubuntu-server/2017-October/007605.html
+  - 0.7.1: https://lists.ubuntu.com/archives/ubuntu-server/2018-March/007667.html
+
+The git log can be referred to for changes worth mentioning:
+
+  $ git log --stat ${LAST_RELEASE}..
+
+If desired, a shortlog can be appended to the release announcement, to
+itemize all changes:
+
+  $  git shortlog ${LAST_RELEASE}...
+
+
+3.  Testing
+-----------
+
+First check there are no unexpected test failures in trunk:
+
+  $ python3 ./setup.py check
+  $ python3 ./setup.py build
+  $ pytest-3 .
+
+Optionally, the full test suite can be directly executed, although since
+it has some rather exacting dependencies, it may not be able to build
+properly.
+
+  $ python3 ./setup.py test
+
+Next, push a copy of the branch up to launchpad under your own namespace
+for Continuous Integration (CI) testing:
+
+  $ git push ${LP_USERNAME} ${VERSION}-release
+
+Go to the Launchpad page for the branch and create a merge proposal
+targeted to lp:git-ubuntu, set 'main' as the Target branch and set
+the Description to say "For CI build only".  Review type can be set to
+'ci'.  This will ensure the regular CI runs on it, which exercises the
+snap build mechanics, but let's the development team know it can be
+ignored for review purposes.  This isn't the snap we'll actually be
+using, but will produce one we can download and inspect.
+
+A snap candidate (not yet uploaded to the store) can be installed
+locally for testing like this:
+
+  $ lxc exec ${CONTAINER} -- rm /tmp/git-ubuntu_0+git.*_amd64.snap
+  $ lxc file push ./git-ubuntu_0+git.*_amd64.snap ${CONTAINER}/tmp
+  $ lxc exec ${CONTAINER} -- bash
+  $ sudo snap install --classic --dangerous /tmp/git-ubuntu_0+git.*_amd64.snap
+
+The snap package itself can be locally mounted directly as a filesystem,
+which can be helpful for evaluating its contents.  For example, to look
+at what Python modules are included:
+
+  $ mkdir /tmp/snap
+  $ sudo mount git-ubuntu_0+git.59a1e51_amd64.snap /tmp/snap/
+  $ ls /tmp/snap/usr/lib/python3.6/
+  $ cd ${HOME} && umount /tmp/snap && rmdir /tmp/snap
+
+
+4.  Release the new version
+---------------------------
+
+Once everything looks good, merge the change from your local release branch to master:
+
+  $ git checkout master
+  $ git merge --ff-only ${VERSION}-release
+
+Make sure everything looks ok.  The status should show no uncommitted
+changes, etc.  Verify the log shows the correct tags and that HEAD
+points to master, etc.  Doublecheck that git describe displays
+${VERSION}:
+
+  $ git status
+  $ git log --oneline --decorate=short
+  $ git describe
+
+If all looks good, now push the annotated tag and code changes to origin:
+
+  $ git push origin master ${VERSION}
+
+
+5. Publish Snap
+---------------
+
+Channels used for delivering the snap package are defined as follows:
+
+  - EDGE: Tracks the latest code in master to allow testing of
+    potentially unstable work.  This is not recommended for general
+    usage by end users.
+
+  - BETA: Most of the time, this channel will track the same version as
+    in STABLE, but also delivers release candidates and sometimes may
+    provide early access to new features or bug fixes.  This channel is
+    recommended particularly for advanced git-ubuntu users who wish to
+    participate in testing activities.  It is also the channel used for
+    the importer on the server.
+
+  - STABLE: This channel tracks the current release used in the
+    git-ubuntu service itself.  This is the recommended channel for
+    all end users.
+
+You will initially publish the package to EDGE only to verify it builds
+properly.
+
+First, trigger a rebuild of the snap in the server team's Jenkins
+instance.  The git push from step #4 will get picked up by the nightly
+builder, but if you don't wish to wait a day for the build, you can
+manually trigger it on this page:
+
+  https://jenkins.ubuntu.com/server/job/git-ubuntu-ci-nightly/
+
+Make sure you're logged into Jenkins, then click
+
+  "Build Now"
+
+Once this is done, download the snap from Jenkins.  It should be listed
+under Last Successful Artifacts on this page:
+
+  https://jenkins.ubuntu.com/server/job/git-ubuntu-ci-nightly/
+
+Next, verify you have your snapcraft account configured, logged in, and
+working locally:
+
+  $ snapcraft whoami
+  $ snap list
+
+Finally, upload the snap to EDGE:
+
+  $ snapcraft push --release edge ./git-ubuntu_${VERSION}+git<whatever>_amd64.snap
+
+The command will block for a few minutes while the store analyzes the
+snap. Once it is approved, it will become available in the edge channel.
+
+For anything but trivial releases, you should then `snap install` the
+edge version of the package in a test environment to verify it.
+
+Once you deem it good to go, use the Snapcraft website
+(https://snapcraft.io/git-ubuntu/releases) to copy the snap to BETA, and
+proceed with installing it in production (next step).  Solicit broader
+testing, as appropriate, and then after a sufficient amount of testing
+time (e.g. a week or so) copy the snap to STABLE.
+
+
+6. Installation to Production
+-----------------------------
+
+See our internal process documentation for details on how to do this.
+
+
+7. Announce Release
+-------------------
+
+Email the (gpg signed) announcement to:
+
+  To: [e-mail]
+  Cc: [e-mail]
+
+Upload a copy of the announcement to https://launchpad.net/git-ubuntu/
+
+
+8. Close bugs
+-------------
+
+Close all bugs fixed by this release. Here's an example that can be run
+from `lp-shell` to close all bug tasks marked "Fix Committed". If you
+use this, remember to change `VERSION` appropriately:
+
+    VERSION = '1.0'
+    tasks = list(lp.projects['git-ubuntu'].searchTasks(status='Fix Committed'))
+    bugs = [lp.load(bug_link) for bug_link in set(task.bug_link for task in tasks)]
+    for bug in bugs:
+        bug.newMessage(
+            subject=f'Fix released in git-ubuntu',
+            content=f'Fix released in git-ubuntu version {VERSION}',
+        )
+    for task in tasks:
+        task.status = 'Fix Released'
+        task.lp_save()
+
+
+9. Update Trello Card
+---------------------
+
+If a card hasn't been created in the daily-ubuntu-server board for the
+release task already, add one at this point.  Add yourself as a member
+of the card, and add labels 'git-ubuntu' and 'highlight'.  The latter
+label flags it to be mentioned in the week's Ubuntu Server Developer Summary.
+
+
+10. Discourse Blogging (Optional)
+--------------------------------
+
+If desired, follow up with one or more topics/posts to
+discourse.ubuntu.com about the major new features included in the
+release.  Discourse posts shouldn't be done just for ordinary bug
+fixing, and shouldn't simply mirror the release announcement or usage
+documentation.
+>>>>>>> doc/release-process.md
diff --git a/gitubuntu/changelog_date_overrides.txt b/gitubuntu/changelog_date_overrides.txt
new file mode 100644
index 0000000..cdf5e30
--- /dev/null
+++ b/gitubuntu/changelog_date_overrides.txt
@@ -0,0 +1,19 @@
+<<<<<<< gitubuntu/changelog_date_overrides.txt
+=======
+# Package versions that have illegal dates in their changelog entries.
+# In these cases the first seen publication date must be used instead
+# for the author date of a synthesized commit.
+#
+# Note: this file must exactly match the import specification. Before
+# adding an entry here, adjust the specification first.
+
+ghostscript 9.50~dfsg-5ubuntu4
+gmsh 2.0.7-1.2ubuntu1
+iscsitarget 0.4.15+svn148-2.1ubuntu1
+lxqt-config 0.13.0-0ubuntu4
+mail-spf-perl 2.004-0ubuntu1
+nut 2.2.0-2
+prips 0.9.4-3
+prometheus-alertmanager 0.15.3+ds-3ubuntu1
+software-properties 0.80
+>>>>>>> gitubuntu/changelog_date_overrides.txt
diff --git a/gitubuntu/changelog_tests/maintainer_name_inner_space b/gitubuntu/changelog_tests/maintainer_name_inner_space
new file mode 100644
index 0000000..17cc421
--- /dev/null
+++ b/gitubuntu/changelog_tests/maintainer_name_inner_space
@@ -0,0 +1,8 @@
+<<<<<<< gitubuntu/changelog_tests/maintainer_name_inner_space
+=======
+testpkg (1.0) xenial; urgency=medium
+
+  * Sample entry.
+
+ -- Test  Maintainer <[e-mail]>  Thu, 01 Jan 1970 00:00:00 +0000
+>>>>>>> gitubuntu/changelog_tests/maintainer_name_inner_space
diff --git a/gitubuntu/changelog_tests/maintainer_name_leading_space b/gitubuntu/changelog_tests/maintainer_name_leading_space
new file mode 100644
index 0000000..07e9dd8
--- /dev/null
+++ b/gitubuntu/changelog_tests/maintainer_name_leading_space
@@ -0,0 +1,8 @@
+<<<<<<< gitubuntu/changelog_tests/maintainer_name_leading_space
+=======
+testpkg (1.0) xenial; urgency=medium
+
+  * Sample entry.
+
+ --  Test Maintainer <[e-mail]>  Thu, 01 Jan 1970 00:00:00 +0000
+>>>>>>> gitubuntu/changelog_tests/maintainer_name_leading_space
diff --git a/gitubuntu/changelog_tests/maintainer_name_trailing_space b/gitubuntu/changelog_tests/maintainer_name_trailing_space
new file mode 100644
index 0000000..358b4a3
--- /dev/null
+++ b/gitubuntu/changelog_tests/maintainer_name_trailing_space
@@ -0,0 +1,8 @@
+<<<<<<< gitubuntu/changelog_tests/maintainer_name_trailing_space
+=======
+testpkg (1.0) xenial; urgency=medium
+
+  * Sample entry.
+
+ -- Test Maintainer  <[e-mail]>  Thu, 01 Jan 1970 00:00:00 +0000
+>>>>>>> gitubuntu/changelog_tests/maintainer_name_trailing_space
diff --git a/gitubuntu/changelog_tests/test_date_1 b/gitubuntu/changelog_tests/test_date_1
new file mode 100644
index 0000000..3c54cec
--- /dev/null
+++ b/gitubuntu/changelog_tests/test_date_1
@@ -0,0 +1,8 @@
+<<<<<<< gitubuntu/changelog_tests/test_date_1
+=======
+testpkg (1.0) xenial; urgency=medium
+
+  * Sample entry.
+
+ -- Test Maintainer <[e-mail]>  Mon, 12 May 2016 08:14:34 -0700
+>>>>>>> gitubuntu/changelog_tests/test_date_1
diff --git a/gitubuntu/changelog_tests/test_date_2 b/gitubuntu/changelog_tests/test_date_2
new file mode 100644
index 0000000..9defc1f
--- /dev/null
+++ b/gitubuntu/changelog_tests/test_date_2
@@ -0,0 +1,8 @@
+<<<<<<< gitubuntu/changelog_tests/test_date_2
+=======
+testpkg (1.0) xenial; urgency=medium
+
+  * Sample entry.
+
+ -- Test Maintainer <[e-mail]>  Mon, 12 May 2016 08:14:34 -0700 
+>>>>>>> gitubuntu/changelog_tests/test_date_2
diff --git a/gitubuntu/changelog_tests/test_distribution b/gitubuntu/changelog_tests/test_distribution
new file mode 100644
index 0000000..099b2b2
--- /dev/null
+++ b/gitubuntu/changelog_tests/test_distribution
@@ -0,0 +1,8 @@
+<<<<<<< gitubuntu/changelog_tests/test_distribution
+=======
+testpkg (1.0) xenial; urgency=medium
+
+  * Sample entry.
+
+ -- Test Maintainer <[e-mail]>  Mon, 12 May 2016 08:14:34 -0700
+>>>>>>> gitubuntu/changelog_tests/test_distribution
diff --git a/gitubuntu/changelog_tests/test_distribution_source_1 b/gitubuntu/changelog_tests/test_distribution_source_1
new file mode 100644
index 0000000..dbb4587
--- /dev/null
+++ b/gitubuntu/changelog_tests/test_distribution_source_1
@@ -0,0 +1,8 @@
+<<<<<<< gitubuntu/changelog_tests/test_distribution_source_1
+=======
+testpkg (1.0) xenial; urgency=medium
+
+  * Sample entry.
+
+ -- Test Maintainer <[e-mail]>  Mon, 12 May 2016 08:14:34 -0700
+>>>>>>> gitubuntu/changelog_tests/test_distribution_source_1
diff --git a/gitubuntu/changelog_tests/test_distribution_source_2 b/gitubuntu/changelog_tests/test_distribution_source_2
new file mode 100644
index 0000000..04abafe
--- /dev/null
+++ b/gitubuntu/changelog_tests/test_distribution_source_2
@@ -0,0 +1,8 @@
+<<<<<<< gitubuntu/changelog_tests/test_distribution_source_2
+=======
+testpkg (1.0) zesty-security; urgency=medium
+
+  * Sample entry.
+
+ -- Test Maintainer <[e-mail]>  Mon, 12 May 2016 08:14:34 -0700
+>>>>>>> gitubuntu/changelog_tests/test_distribution_source_2
diff --git a/gitubuntu/changelog_tests/test_distribution_source_3 b/gitubuntu/changelog_tests/test_distribution_source_3
new file mode 100644
index 0000000..f89aa4a
--- /dev/null
+++ b/gitubuntu/changelog_tests/test_distribution_source_3
@@ -0,0 +1,8 @@
+<<<<<<< gitubuntu/changelog_tests/test_distribution_source_3
+=======
+testpkg (1.0) unstable; urgency=medium
+
+  * Sample entry.
+
+ -- Test Maintainer <[e-mail]>  Mon, 12 May 2016 08:14:34 -0700
+>>>>>>> gitubuntu/changelog_tests/test_distribution_source_3
diff --git a/gitubuntu/changelog_tests/test_distribution_source_4 b/gitubuntu/changelog_tests/test_distribution_source_4
new file mode 100644
index 0000000..8c8fb68
--- /dev/null
+++ b/gitubuntu/changelog_tests/test_distribution_source_4
@@ -0,0 +1,8 @@
+<<<<<<< gitubuntu/changelog_tests/test_distribution_source_4
+=======
+testpkg (1.0) devel; urgency=medium
+
+  * Sample entry.
+
+ -- Test Maintainer <[e-mail]>  Mon, 12 May 2016 08:14:34 -0700
+>>>>>>> gitubuntu/changelog_tests/test_distribution_source_4
diff --git a/gitubuntu/changelog_tests/test_maintainer_1 b/gitubuntu/changelog_tests/test_maintainer_1
new file mode 100644
index 0000000..62a89ff
--- /dev/null
+++ b/gitubuntu/changelog_tests/test_maintainer_1
@@ -0,0 +1,8 @@
+<<<<<<< gitubuntu/changelog_tests/test_maintainer_1
+=======
+testpkg (1.0) xenial; urgency=medium
+
+  * Sample entry.
+
+ -- Test Maintainer <[e-mail]>  Thu, 01 Jan 1970 00:00:00 +0000
+>>>>>>> gitubuntu/changelog_tests/test_maintainer_1
diff --git a/gitubuntu/changelog_tests/test_maintainer_2 b/gitubuntu/changelog_tests/test_maintainer_2
new file mode 100644
index 0000000..7b8db29
--- /dev/null
+++ b/gitubuntu/changelog_tests/test_maintainer_2
@@ -0,0 +1,8 @@
+<<<<<<< gitubuntu/changelog_tests/test_maintainer_2
+=======
+testpkg (1.0) xenial; urgency=medium
+
+  * Sample entry.
+
+ --  <[e-mail]>  Thu, 01 Jan 1970 00:00:00 +0000
+>>>>>>> gitubuntu/changelog_tests/test_maintainer_2
diff --git a/gitubuntu/changelog_tests/test_maintainer_3 b/gitubuntu/changelog_tests/test_maintainer_3
new file mode 100644
index 0000000..195564a
--- /dev/null
+++ b/gitubuntu/changelog_tests/test_maintainer_3
@@ -0,0 +1,8 @@
+<<<<<<< gitubuntu/changelog_tests/test_maintainer_3
+=======
+testpkg (1.0) xenial; urgency=medium
+
+  * Sample entry.
+
+ -- <[e-mail]>  Thu, 01 Jan 1970 00:00:00 +0000
+>>>>>>> gitubuntu/changelog_tests/test_maintainer_3
diff --git a/gitubuntu/changelog_tests/test_versions_1 b/gitubuntu/changelog_tests/test_versions_1
new file mode 100644
index 0000000..ec94bc5
--- /dev/null
+++ b/gitubuntu/changelog_tests/test_versions_1
@@ -0,0 +1,8 @@
+<<<<<<< gitubuntu/changelog_tests/test_versions_1
+=======
+testpkg (1.0) xenial; urgency=medium
+
+  * Sample entry.
+
+ -- Test Maintainer <[e-mail]>  Mon, 12 May 2016 08:14:34 -0700
+>>>>>>> gitubuntu/changelog_tests/test_versions_1
diff --git a/gitubuntu/changelog_tests/test_versions_2 b/gitubuntu/changelog_tests/test_versions_2
new file mode 100644
index 0000000..ed6ade9
--- /dev/null
+++ b/gitubuntu/changelog_tests/test_versions_2
@@ -0,0 +1,14 @@
+<<<<<<< gitubuntu/changelog_tests/test_versions_2
+=======
+testpkg (2.0) xenial; urgency=medium
+
+  * Sample entry 2.
+
+ -- Test Maintainer <[e-mail]>  Mon, 27 Aug 2016 12:10:34 -0700
+
+testpkg (1.0) xenial; urgency=medium
+
+  * Sample entry 1.
+
+ -- Test Maintainer <[e-mail]>  Mon, 12 May 2016 08:14:34 -0700
+>>>>>>> gitubuntu/changelog_tests/test_versions_2
diff --git a/gitubuntu/changelog_tests/test_versions_3 b/gitubuntu/changelog_tests/test_versions_3
new file mode 100644
index 0000000..8fbf944
--- /dev/null
+++ b/gitubuntu/changelog_tests/test_versions_3
@@ -0,0 +1,26 @@
+<<<<<<< gitubuntu/changelog_tests/test_versions_3
+=======
+testpkg (4.0) zesty; urgency=medium
+
+  * Sample entry 4.
+
+ -- Test Maintainer <[e-mail]>  Mon, 03 Apr 2017 18:04:01 -0700
+
+testpkg (3.0) yakkety; urgency=medium
+
+  * Sample entry 3.
+
+ -- Test Maintainer <[e-mail]>  Fri, 10 Nov 2016 03:34:10 -0700
+
+testpkg (2.0) xenial; urgency=medium
+
+  * Sample entry 2.
+
+ -- Test Maintainer <[e-mail]>  Sat, 27 Aug 2016 12:10:55 -0700
+
+testpkg (1.0) xenial; urgency=medium
+
+  * Sample entry 1.
+
+ -- Test Maintainer <[e-mail]>  Thu, 12 May 2016 08:14:34 -0700
+>>>>>>> gitubuntu/changelog_tests/test_versions_3
diff --git a/gitubuntu/clone.py b/gitubuntu/clone.py
new file mode 100644
index 0000000..aff52be
--- /dev/null
+++ b/gitubuntu/clone.py
@@ -0,0 +1,178 @@
+<<<<<<< gitubuntu/clone.py
+=======
+import argparse
+import logging
+import os
+import re
+import shutil
+from subprocess import CalledProcessError
+import sys
+from gitubuntu.__main__ import top_level_defaults
+from gitubuntu.git_repository import (
+    GitUbuntuRepository,
+    GitUbuntuRepositoryFetchError,
+)
+from gitubuntu.run import decode_binary, run
+
+import pkg_resources
+import pygit2
+
+def copy_hooks(src, dst):
+    try:
+        os.mkdir(dst)
+    except FileExistsError:
+        pass
+
+    for hook in os.listdir(src):
+        shutil.copy2(
+            os.path.join(src, hook),
+            dst,
+        )
+
+def main(
+    package,
+    directory=None,
+    lp_user=None,
+    proto=top_level_defaults.proto,
+):
+    """Entry point to clone subcommand
+
+    @package: Name of source package
+    @directory: directory to clone the repository into
+    @lp_user: user to authenticate to Launchpad as
+    @proto: string protocol to use (one of 'http', 'https', 'git')
+
+    If directory is None, a relative directory with the same name as
+    package will be used.
+
+    If lp_user is None, value of `git config gitubuntu.lpuser` will be
+    used.
+
+    Returns the resulting GitUbuntuRepository object, if successful;
+    None otherwise.
+    """
+    directory = (
+        os.path.abspath(directory)
+        if directory
+        else os.path.join(os.path.abspath(os.getcwd()), package)
+    )
+    if os.path.isdir(directory):
+        logging.error('directory %s exists' % directory)
+        return None
+
+    local_repo = GitUbuntuRepository(
+        local_dir=directory,
+        lp_user=lp_user,
+        fetch_proto=proto,
+    )
+
+    copy_hooks(
+        pkg_resources.resource_filename(
+           'gitubuntu',
+           'hooks',
+        ),
+        os.path.join(
+            directory,
+            os.getenv('GIT_DIR', '.git'),
+            'hooks',
+        ),
+    )
+
+    local_repo.add_base_remotes(package)
+    try:
+        local_repo.fetch_base_remotes(verbose=True)
+    except GitUbuntuRepositoryFetchError:
+        logging.error("Unable to find an imported repository for %s. "
+            "Please request an import by e-mailing "
+            "[e-mail].",
+            package
+        )
+        shutil.rmtree(local_repo.local_dir)
+        return None
+
+    local_repo.add_lpuser_remote(pkgname=package)
+    logging.debug("added remote '%s' -> %s", local_repo.lp_user,
+        local_repo.raw_repo.remotes[local_repo.lp_user].url
+    )
+    try:
+        local_repo.fetch_lpuser_remote(verbose=True)
+    except GitUbuntuRepositoryFetchError:
+        pass
+
+    try:
+        local_repo.create_tracking_branch(
+            'ubuntu/devel',
+            'pkg/ubuntu/devel'
+        )
+        local_repo.checkout_commitish('ubuntu/devel')
+    except:
+        logging.error('Unable to checkout ubuntu/devel, does '
+            'pkg/ubuntu/devel branch exist?'
+        )
+
+    local_repo.git_run(['config', 'notes.displayRef', 'refs/notes/changelog'])
+
+    if os.path.isfile(os.path.join(directory, '.gitignore')):
+        logging.warning('A .gitignore file exists in the source '
+            'package. This will affect the behavior of git. Consider '
+            'backing up the gitignore while working on this package '
+            'to ensure all changes are tracked or passing appropriate '
+            'flags to git commands (e.g., git status --ignored).'
+        )
+
+    return local_repo
+
+def parse_args(subparsers=None, base_subparsers=None):
+    kwargs = dict(
+        description='Clone a source package git repository to a directory',
+        formatter_class=argparse.RawTextHelpFormatter,
+        epilog='''
+Example:
+   * clone to open-iscsi/
+     %(prog)s open-iscsi
+   * clone to ubuntu.git
+     %(prog)s open-iscsi ubuntu.git
+   * use git rather than https protocol for remotes:
+     %(prog)s --proto=git open-iscsi
+'''
+                 )
+    if base_subparsers:
+        kwargs['parents'] = base_subparsers
+    if subparsers:
+        parser = subparsers.add_parser('clone', **kwargs)
+        parser.set_defaults(func=cli_main)
+    else:
+        parser = argparse.ArgumentParser(**kwargs)
+    parser.add_argument('package', type=str,
+        help='Name of source package to clone'
+    )
+    parser.add_argument('directory', type=str,
+        help='Local directory to clone to. If not specified, a '
+             ' directory with the same name as PACKAGE will be '
+             'used',
+        default=None,
+        nargs='?'
+    )
+    parser.add_argument('-l', '--lp-user', type=str, help=argparse.SUPPRESS)
+    if not subparsers:
+        return parser.parse_args()
+    return 'clone - %s' % kwargs['description']
+
+def cli_main(args):
+    try:
+        lp_user = args.lp_user
+    except AttributeError:
+        lp_user = None
+
+    if main(
+        package=args.package,
+        directory=args.directory,
+        lp_user=lp_user,
+        proto=args.proto,
+    ) is not None:
+        return 0
+    return 1
+
+
+# vi: ts=4 expandtab
+>>>>>>> gitubuntu/clone.py
diff --git a/gitubuntu/git_repository.py b/gitubuntu/git_repository.py
new file mode 100644
index 0000000..9a81860
--- /dev/null
+++ b/gitubuntu/git_repository.py
@@ -0,0 +1,3026 @@
+<<<<<<< gitubuntu/git_repository.py
+=======
+### XXX: can we reduce number of calls to dpkg-parsechangelog
+### XXX: is any of this data in lp already?
+
+import collections
+from contextlib import contextmanager
+from copy import copy
+import datetime
+import enum
+from functools import lru_cache
+import itertools
+import logging
+import os
+import posixpath
+import re
+import shutil
+import stat
+from subprocess import CalledProcessError
+import sys
+import tempfile
+from gitubuntu.__main__ import top_level_defaults
+import gitubuntu.build
+from gitubuntu.dsc import component_tarball_matches
+from gitubuntu.patch_state import PatchState
+from gitubuntu.run import (
+   decode_binary,
+   run,
+   runq,
+   run_gbp,
+   run_quilt,
+)
+import gitubuntu.spec
+from gitubuntu.test_util import get_test_changelog
+import gitubuntu.versioning
+import debian.changelog
+import debian.debian_support
+import pygit2
+import pytest
+
+
+def _follow_symlinks_to_blob(repo, top_tree_object, search_path,
+    _rel_tree=None, _rel_path=''
+):
+    '''Recursively follow a path down a tree, following symlinks, to find blob
+
+    repo: pygit2.Repository object
+    top_tree: pygit2.Tree object of the top of the tree structure
+    search_path: '/'-separated path string of blob to find
+    _rel_tree: (internal) which tree to look further into
+    _rel_path: (internal) the path we are in so far
+    '''
+
+    NORMAL_BLOB_MODES = set([
+        pygit2.GIT_FILEMODE_BLOB,
+        pygit2.GIT_FILEMODE_BLOB_EXECUTABLE,
+    ])
+
+    _rel_tree = _rel_tree or top_tree_object
+    head, tail = posixpath.split(search_path)
+
+    # A traditional functional split would put a single entry in head with tail
+    # empty, but posixpath.split doesn't necessarily do this. Jiggle it round
+    # to make it appear to have traditional semantics.
+    if not head:
+        head = tail
+        tail = None
+
+    entry = _rel_tree[head]
+    if entry.type in [pygit2.GIT_OBJ_TREE, 'tree']:
+        return _follow_symlinks_to_blob(
+            repo=repo,
+            top_tree_object=top_tree_object,
+            search_path=tail,
+            _rel_tree=repo.get(entry.id),
+            _rel_path=posixpath.join(_rel_path, head),
+        )
+    elif entry.type in [pygit2.GIT_OBJ_BLOB, 'blob'] and entry.filemode == pygit2.GIT_FILEMODE_LINK:
+        # Found a symlink. Start again from the top with adjustment for symlink
+        # following
+        target_tail = [decode_binary(repo.get(entry.id).data)]
+        if tail is not None:
+            target_tail.append(tail)
+        search_path = posixpath.normpath(
+            posixpath.join(_rel_path, *target_tail)
+        )
+        return _follow_symlinks_to_blob(
+            repo=repo,
+            top_tree_object=top_tree_object,
+            search_path=search_path,
+        )
+    elif entry.type in [pygit2.GIT_OBJ_BLOB, 'blob'] and entry.filemode in NORMAL_BLOB_MODES:
+        return repo.get(entry.id)
+    else:
+        # Found some special entry such as a "gitlink" (submodule entry)
+        raise ValueError(
+            "Found %r filemode %r looking for %r" %
+                (entry, entry.filemode, posixpath.join(_rel_path, search_path))
+        )
+
+
+def follow_symlinks_to_blob(repo, treeish_object, path):
+    return _follow_symlinks_to_blob(
+        repo=repo,
+        top_tree_object=treeish_object.peel(pygit2.Tree),
+        search_path=posixpath.normpath(path),
+    )
+
+
+def _derive_git_cli_env(
+    pygit2_repo,
+    initial_env=None,
+    update_env=None,
+    work_tree_path=None,
+    index_path=None,
+):
+    """Calculate the environment to be used in a call to the git CLI
+
+    :param pygit2.Repository pygit2_repo: the repository for which to calculate
+        the environment
+    :param dict initial_env: the environment to start with
+    :param dict update_env: additional environment setings with which to
+        override the result
+    :param str work_tree_path: in the case of an alternate work tree being
+        used, specify this here and GIT_WORK_TREE will be set to it instead of
+        the default being taken from the work tree used by pygit2_repo
+    :param str index_path: if an alternate index is being used, specify it here
+        and GIT_INDEX_FILE will be set accordingly.
+    :rtype: dict
+    :returns: a dictionary representing the environment with which to call the
+        git CLI
+
+    This function encapsulates the setting of the GIT_DIR, GIT_WORK_TREE and
+    GIT_INDEX_FILE environment variables as necessary. The provided
+    pygit2.Repository instance is used to determine these values. initial_env,
+    if provided, specifies the initial environment to use instead of defaulting
+    to the process' current environment. update_env allows extra environment
+    variables to be added as well as the override of any variables set by this
+    function, including GIT_DIR, GIT_WORK_TREE and GIT_INDEX_FILE.
+    """
+    if initial_env is None:
+        env = os.environ.copy()
+    else:
+        env = initial_env.copy()
+
+    env['GIT_DIR'] = pygit2_repo.path
+
+    if work_tree_path is None:
+        env['GIT_WORK_TREE'] = pygit2_repo.workdir
+    else:
+        env['GIT_WORK_TREE'] = work_tree_path
+
+    if index_path is not None:
+        env['GIT_INDEX_FILE'] = index_path
+
+    if update_env:
+        env.update(update_env)
+
+    return env
+
+
+def _derive_target_branch_string(remote_branch_objects):
+    '''Given a list of branch objects, return the name of the one to use as the target branch
+
+    Returns either one of the branch objects' names, or the empty string
+    to indicate no suitable candidate.
+    '''
+    if len(remote_branch_objects) == 0:
+        logging.error("Unable to automatically determine importer "
+            "branch: No candidate branches found."
+        )
+        return ''
+    remote_branch_strings = [
+        b.branch_name for b in remote_branch_objects
+    ]
+    if len(remote_branch_objects) > 1:
+        # do the trees of each branch's tip match?
+        if len(
+            set(b.peel(pygit2.Tree).id for b in remote_branch_objects)
+        ) != 1:
+            logging.error("Unable to automatically determine importer "
+                "branch: Multiple candidate branches found and "
+                "their trees do not match: %s. This might be a "
+                "bug in `git ubuntu lint`, please report it at "
+                "https://bugs.launchpad.net/git-ubuntu. "
+                "Please pass  --target-branch.",
+                ", ".join(remote_branch_strings)
+            )
+            return ''
+        # is ubuntu/devel one of the candidates?
+        try:
+            return [
+                b for b in remote_branch_strings if 'ubuntu/devel' in b
+            ].pop()
+        except IndexError:
+            pass
+        # are all candidate branches for the same series?
+        pkg_remote_branch_serieses = set(
+            # remove the prefix, trim the distribution and
+            # extract the series
+            b[len('pkg/'):].split('/')[1].split('-')[0] for
+            b in remote_branch_strings
+        )
+        if len(pkg_remote_branch_serieses) != 1:
+            logging.error("Unable to automatically determine importer "
+                "branch: Multiple candidate branches found and "
+                "they do not target the same series: %s. Please pass "
+                "--target-branch.", ", ".join(remote_branch_strings)
+            )
+            return ''
+        # is a -devel branch present?
+        if not any('-devel' in b for b in remote_branch_strings):
+            logging.error("Unable to automatically determine importer "
+                "branch: Multiple candidate branches found and "
+                "none appear to be a -devel branch: %s. Please "
+                "pass  --target-branch.", ", ".join(remote_branch_strings)
+            )
+            return ''
+        # if so, favor -devel
+        remote_branch_strings = [
+            b for b in remote_branch_strings if '-devel' in b
+        ]
+    return remote_branch_strings.pop()
+
+def derive_target_branch(repo, commitish_string, namespace='pkg'):
+    return _derive_target_branch_string(
+        repo.nearest_remote_branches(commitish_string, namespace)
+    )
+
+
+def git_run(
+    pygit2_repo,
+    args,
+    initial_env=None,
+    update_env=None,
+    work_tree_path=None,
+    index_path=None,
+    **kwargs
+):
+    """Run the git CLI with the provided arguments
+
+    :param pygit2.Repository: the repository on which to act
+    :param list(str) args: arguments to the git CLI
+    :param dict initial_env: the environment to use
+    :param dict update_env: additional environment variables and overrides
+    :param dict **kwargs: further arguments to pass through to
+        gitubuntu.run.run()
+    :raises subprocess.CalledProcessError: if git exits non-zero
+    :rtype: (str, str)
+    :returns: stdout and stderr strings containing the subprocess output
+
+    If initial_env is not set, it defaults to the current process' environment.
+
+    The GIT_DIR, GIT_WORK_TREE and GIT_INDEX_FILE environment variables are set
+    automatically as necessary based on the repository's existing location and
+    settings.
+
+    If update_env is set, then the environment to be used is updated with env
+    before the call to git is made. This can override GIT_DIR,
+    GIT_WORK_TREE, GIT_INDEX_FILE and anything else.
+    """
+    env = _derive_git_cli_env(
+        pygit2_repo=pygit2_repo,
+        initial_env=initial_env,
+        update_env=update_env,
+        work_tree_path=work_tree_path,
+        index_path=index_path,
+    )
+    return run(['git'] + list(args), env=env, **kwargs)
+
+
+class RenameableDir:
+    """An on-disk directory that can be renamed and traversed recursively.
+
+    This is a thin wrapper around a filesystem path string (and must be
+    instantiated with one). Methods and attributes are modeled around a
+    py.path, but we do not use py.path as we don't really need its
+    functionality and it would add another dependency. This interface allows
+    for filesystem operations to be easily faked with a FakeRenameableDir for
+    testing consumers of this class.
+
+    One wart around renaming and py.path is that once renamed a py.path object
+    becomes useless as it no longer validly refers to an on-disk path. Rather
+    than supporting a rename method, this wrapper provides a basename
+    setter to handle the rename and replacement wrapped string object
+    transparently. This moves complexity away from the class consumer, allowing
+    the consumer to be tested more easily.
+
+    Since the underlying purpose of this class is to handle manipulations of a
+    directory tree for adjustments needed during import/export, symlink
+    handling is effectively "turned off" in the specification of this class.
+    Symlinks to directories are not recursed into; they are handled no
+    differently to a regular file, in the same manner as lstat(2).
+    """
+    def __init__(self, path):
+        """Create a new RenameableDir instance.
+
+        :param str path: the on-disk directory to wrap, which must exist. For
+            symlinks, it is the symlink itself that must exist; the existence
+            of a symlink's target does not matter.
+        :raises FileNotFoundError: if the path supplied does not exist.
+        """
+        # Ignore the return value of os.lstat(); this call is used to raise
+        # FileNotFoundError if the path does not exist (as required in the spec
+        # specified by the docstring), or succeed otherwise. The
+        # call for os.path.lexists() would use the same underlying system call
+        # anyway, so this is equivalent and this way we end up with a full
+        # FileNotFoundError exception created for us with all the correct
+        # parameters.
+        os.lstat(path)
+
+        self._path = path
+
+    @property
+    def basename(self):
+        """The name of the directory itself."""
+        return os.path.basename(self._path)
+
+    @basename.setter
+    def basename(self, new_basename):
+        """Rename this directory."""
+        renamed_path = os.path.join(os.path.dirname(self._path), new_basename)
+        os.rename(self._path, renamed_path)
+        self._path = renamed_path
+
+    def listdir(self, fil=lambda x: True):
+        """Return subdirectory objects.
+
+        :param fil: a function that, given a basename, returns a boolean
+            indicating whether or not the corresponding object should be
+            returned in the results.
+        """
+        return [
+            RenameableDir(os.path.join(self._path, p))
+            for p in os.listdir(self._path)
+            if fil(p)
+        ]
+
+    @property
+    def recursive(self):
+        """Indicate if this object can contain subdirectory objects.
+
+        An object representing a file will return False. An object representing
+        a directory will return True, even if it is empty.
+
+        Symlinks return False even if they point to a directory. Broken
+        symlinks also always return False.
+
+        :rtype: bool
+        """
+        st = os.stat(self._path, follow_symlinks=False)
+        return stat.S_ISDIR(st.st_mode)
+
+    def __str__(self):
+        return str(self._path)
+
+    def __repr__(self):
+        return 'RenameableDir(%r)' % str(self)
+
+    def __hash__(self):
+        # https://stackoverflow.com/q/2909106/478206
+        return hash((
+            type(self),
+            self._path
+        ))
+
+    def __eq__(self, other):
+        return hash(self) == hash(other)
+
+
+class FakeRenameableDir:
+    """A fake RenameDir that retains its structure in memory.
+
+    This is useful for testing consumers of a RenameableDir.
+
+    In addition, renames are recorded and those records passed up to parent
+    FakeRenameableDir objects so that the order of renames that occur can be
+    checked later.
+    """
+    def __init__(self, basename, subdirs):
+        """Create a new RenameableDir instance.
+
+        :param str basename: the basename of this instance.
+        :param subdirs: FakeRenameableDir objects contained within this one.
+            For non-recursive objects (such as those intended to represent
+            files), use None.
+        :type subdirs: list(FakeRenameableDir)
+        """
+        self._basename = basename
+        self._subdirs = subdirs
+
+        if self._subdirs:
+            for subdir in self._subdirs:
+                subdir._parent = self
+
+        self._parent = None
+        self._rename_record = []
+
+    @property
+    def basename(self):
+        return self._basename
+
+    @basename.setter
+    def basename(self, new_basename):
+        self._record_rename(self)
+        self._basename = new_basename
+
+    def _record_rename(self, obj):
+        self._rename_record.append(obj)
+        if self._parent:
+            self._parent._record_rename(obj)
+
+    def listdir(self, fil=lambda x: True):
+        return (subdir for subdir in self._subdirs if fil(subdir.basename))
+
+    @property
+    def recursive(self):
+        return self._subdirs is not None
+
+    def __hash__(self):
+        # https://stackoverflow.com/q/2909106/478206
+        return hash((
+            type(self),
+            self.basename,
+            None if self._subdirs is None else tuple(self._subdirs),
+        ))
+
+    def __eq__(self, other):
+        return hash(self) == hash(other)
+
+    def __repr__(self):
+        return 'FakeRenameableDir(%r, %r)' % (self.basename, self._subdirs)
+
+
+_dot_git_match = re.compile(r'^\.+git$').search
+_EscapeDirection = enum.Enum('EscapeDirection', ['ESCAPE', 'UNESCAPE'])
+
+
+def _escape_unescape_dot_git(path, direction):
+    """Escape or unescape .git entries in a directory recursively.
+
+    :param RenameableDir path: top of directory tree to escape or unescape.
+    :param _EscapeDirection direction: whether to escape or unescape.
+
+    Escaping rules:
+        .git -> ..git
+        ..git -> ...git
+        ...git -> ....git
+        etc.
+
+        All these escaping rules apply all of the time, regardless of whether
+        or not .git exists. Only names matching '.git' with zero or more '.'
+        prepended are touched.
+
+    This allows any directory tree to be losslessly stored in git, since git
+    does not permit entries named '.git'.
+
+    Unescaping is the inverse of escaping. Before unescaping, an entry called
+    '.git' must not exist. If it does, RuntimeError is raised, and the
+    directory is left in an undefined (probably partially unescaped) state.
+    """
+    # When escaping, we have to rename ..git to ...git before renaming .git to
+    # ..git in order to make room, and the reverse for unescaping. If we do the
+    # renames ordered by length of name, we can meet this requirement.
+    # Escaping: order by longest first; unescaping: order by shortest first.
+    sorted_subpaths_to_rename = sorted(
+        path.listdir(fil=_dot_git_match),
+        key=lambda p: len(p.basename),
+        reverse=direction is _EscapeDirection.ESCAPE,
+    )
+    for entry in sorted_subpaths_to_rename:
+        if direction is _EscapeDirection.ESCAPE:
+            # Add a leading '.'
+            entry.basename = '.' + entry.basename
+        else:
+            assert direction is _EscapeDirection.UNESCAPE
+            if entry.basename == '.git':
+                raise RuntimeError(
+                    "%s exists but is invalid when unescaping" % entry,
+                )
+            # Drop the leading '.'
+            assert entry.basename[0] == '.'
+            entry.basename = entry.basename[1:]
+
+    # Traverse the entire directory for recursive escapes;
+    # sorted_subpaths_to_rename is already filtered so is not complete by
+    # itself
+    for entry in path.listdir():
+        if entry.recursive:
+            _escape_unescape_dot_git(entry, direction=direction)
+
+
+def escape_dot_git(path):
+    """Apply .git escaping to a filesystem path.
+
+    :param str path: path to filesystem to change
+    """
+    return _escape_unescape_dot_git(
+        path=RenameableDir(path),
+        direction=_EscapeDirection.ESCAPE,
+    )
+
+
+def unescape_dot_git(path):
+    """Unapply .git escaping to a filesystem path.
+
+    :param str path: path to filesystem to change
+
+    Any entry (including recursively) called '.git' in path is an error and
+    will raise a RuntimeError. If an exception is raised, path may be left in a
+    partially unescaped state.
+    """
+    return _escape_unescape_dot_git(
+        path=RenameableDir(path),
+        direction=_EscapeDirection.UNESCAPE,
+    )
+
+
+class ChangelogError(Exception):
+    pass
+
+class Changelog:
+    '''Representation of a debian/changelog file found inside a git tree-ish
+
+    Uses dpkg-parsechangelog for parsing, but when this fails we fall
+    back to grep/sed-based pattern matching automatically.
+    '''
+    def __init__(self, content_bytes):
+        '''
+        contents: bytes string of file contents
+        '''
+        self._contents = content_bytes
+        try:
+            self._changelog = debian.changelog.Changelog(
+                self._contents,
+                strict=True
+            )
+            if not len(self._changelog.versions):
+                # assume bad read, so fall back to shell later
+                self._changelog = None
+        except (
+            UnicodeDecodeError,
+            ValueError,
+            debian.changelog.ChangelogParseError
+        ):
+            self._changelog = None
+
+    @classmethod
+    def from_treeish(cls, repo, treeish_object):
+        '''
+        repo: pygit2.Repository instance
+        treeish_object: pygit2.Object subclass instance (must peel to pygit2.Tree)
+        '''
+        blob = follow_symlinks_to_blob(
+            repo=repo,
+            treeish_object=treeish_object,
+            path='debian/changelog'
+        )
+        return cls(blob.data)
+
+    @classmethod
+    def from_path(cls, path):
+        with open(path, 'rb') as f:
+            return cls(f.read())
+
+    @lru_cache()
+    def _dpkg_parsechangelog(self, parse_params):
+        stdout, _ = run(
+            'dpkg-parsechangelog -l- %s' % parse_params,
+            input=self._contents,
+            shell=True,
+            verbose_on_failure=False,
+        )
+        return stdout.strip()
+
+    @lru_cache()
+    def _shell(self, cmd):
+        stdout, _ = run(
+            cmd,
+            input=self._contents,
+            shell=True,
+            verbose_on_failure=False,
+        )
+        return stdout.strip()
+
+    @property
+    def _shell_version(self):
+        parse_params = '-n1 -SVersion'
+        shell_cmd = "grep -m1 '^\\S' | sed 's/.*(\\(.*\\)).*/\\1/'"
+        try:
+            raw_out = self._dpkg_parsechangelog(parse_params)
+        except CalledProcessError:
+            raw_out = self._shell(shell_cmd)
+        return None if raw_out == '' else raw_out
+
+    @property
+    def upstream_version(self):
+        if self._changelog:
+           return self._changelog.upstream_version
+        version = self._shell_version
+        m = debian.debian_support.Version.re_valid_version.match(version)
+        if m is None:
+            raise ValueError("Invalid version string: %s", version)
+        return m.group('upstream_version')
+
+    @property
+    def version(self):
+        if self._changelog:
+            try:
+                ret = str(self._changelog.versions[0]).strip()
+                shell_version = self._shell_version
+                if shell_version != 'unknown' and ret != shell_version:
+                    raise ChangelogError(
+                        'Old (%s) and new (%s) changelog values do not agree' %
+                        (self._shell_version, ret)
+                    )
+                return ret
+            except IndexError:
+                return None
+        return self._shell_version
+
+    @property
+    def _shell_previous_version(self):
+        parse_params = '-n1 -o1 -SVersion'
+        shell_cmd = "grep -m1 '^\\S' | tail -1 | sed 's/.*(\\(.*\\)).*/\\1/'"
+        try:
+            raw_out = self._dpkg_parsechangelog(parse_params)
+        except CalledProcessError:
+            raw_out = self._shell(shell_cmd)
+        return None if raw_out == '' else raw_out
+
+    @property
+    def previous_version(self):
+        if self._changelog:
+            try:
+                ret = str(self._changelog.versions[1]).strip()
+                if ret != self._shell_previous_version:
+                    raise ChangelogError(
+                        'Old (%s) and new (%s) changelog values do not agree' %
+                        (self._shell_previous_version, ret)
+                    )
+                return ret
+            except IndexError:
+                return None
+        return self._shell_previous_version
+
+    @property
+    def _shell_maintainer(self):
+        parse_params = '-SMaintainer'
+        shell_cmd = "grep -m1 '^ --' | sed 's/ -- \\(.*\\)  \\(.*\\)/\\1/'"
+        try:
+            return self._dpkg_parsechangelog(parse_params)
+        except CalledProcessError:
+            return self._shell(shell_cmd)
+
+    @property
+    def maintainer(self):
+        if self._changelog:
+            ret = self._changelog.author.strip()
+            if ret != self._shell_maintainer:
+                raise ChangelogError(
+                    'Old (%s) and new (%s) changelog values do not agree' %
+                    (self._shell_maintainer, ret)
+                )
+        else:
+            ret = self._shell_maintainer
+        if not ret:
+            raise ValueError("Unable to parse maintainer from changelog")
+        return ret
+
+    @property
+    def _shell_date(self):
+        parse_params = '-SDate'
+        shell_cmd = "grep -m1 '^ --' | sed 's/ -- \\(.*\\)  \\(.*\\)/\\2/'"
+        try:
+            return self._dpkg_parsechangelog(parse_params)
+        except CalledProcessError:
+            return self._shell(shell_cmd)
+
+    @property
+    def date(self):
+        if self._changelog:
+            ret = self._changelog.date.strip()
+            if ret != self._shell_date:
+                raise ChangelogError(
+                    'Old (%s) and new (%s) changelog values do not agree' %
+                    (self._shell_date, ret)
+                )
+            return ret
+        return self._shell_date
+
+    @property
+    def _shell_all_versions(self):
+        parse_params = '--format rfc822 -SVersion --all'
+        shell_cmd = "grep '^\\S' | sed 's/.*(\\(.*\\)).*/\\1/'"
+        try:
+            version_lines = self._dpkg_parsechangelog(parse_params)
+        except CalledProcessError:
+            version_lines = self._shell(shell_cmd)
+        return [
+            v_stripped
+            for v_stripped in (
+                v.strip() for v in version_lines.splitlines()
+            )
+            if v_stripped
+        ]
+
+    @property
+    def all_versions(self):
+        if self._changelog:
+            ret = [str(v).strip() for v in self._changelog.versions]
+            shell_all_versions = self._shell_all_versions
+            is_equivalent = (
+                len(ret) == len(shell_all_versions) and
+                all(
+                    shell_version == 'unknown' or shell_version == api_version
+                    for shell_version, api_version
+                    in zip(shell_all_versions, ret)
+                )
+            )
+            if not is_equivalent:
+                raise ChangelogError(
+                    "Old and new changelog values do not agree"
+                )
+            return ret
+        else:
+            return self._shell_all_versions
+
+    @property
+    def _shell_distribution(self):
+        parse_params = '-SDistribution'
+        shell_cmd = "grep -m1 '^\\S' | sed 's/.*\\ .*\\ \\(.*\\);.*/\\1/'"
+        try:
+            return self._dpkg_parsechangelog(parse_params)
+        except CalledProcessError:
+            return self._shell(shell_cmd)
+
+    @property
+    def distribution(self):
+        if self._changelog:
+            ret = self._changelog.distributions
+            if ret != self._shell_distribution:
+                raise ChangelogError(
+                    'Old (%s) and new (%s) changelog values do not agree' %
+                    (self._shell_distribution, ret)
+                )
+            return ret
+        return self._shell_distribution
+
+    @property
+    def _shell_srcpkg(self):
+        parse_params = '-SSource'
+        shell_cmd = "grep -m1 '^\\S' | sed 's/\\(.*\\)\\ .*\\ .*;.*/\\1/'"
+        try:
+            return self._dpkg_parsechangelog(parse_params)
+        except CalledProcessError:
+            return self._shell(shell_cmd)
+
+    @property
+    def srcpkg(self):
+        if self._changelog:
+            ret = self._changelog.package.strip()
+            if ret != self._shell_srcpkg:
+                raise ChangelogError(
+                    'Old (%s) and new (%s) changelog values do not agree' %
+                    (self._shell_srcpkg, ret)
+                )
+            return ret
+        return self._shell_srcpkg
+
+    @staticmethod
+    def _parse_changelog_date(changelog_timestamp_string):
+        """Convert changelog timestamp into datetime object
+
+        This function currently requires the locale to have been set to C.UTF-8
+        by the caller. This would typically be done at the main entry point to
+        the importer.
+
+        :param str changelog_timestamp_string: the timestamp part of the the
+            signoff line from a changelog entry
+        :rtype: datetime.datetime
+        :returns: the timestamp as a datetime object
+        :raises ValueError: if the string could not be parsed
+        """
+        # We avoid using something like dateutil.parser here because the
+        # parsing behaviour of malformed or unusually formatted dates must be
+        # precisely as specified and not ever change behaviour. If it did, then
+        # imports would no longer be reproducible.
+        #
+        # However, adding new a form of parsing an unambigious date is
+        # acceptable if the spec is first updated accordingly since that would
+        # only introduce new imports that would have previously failed.
+        #
+        # time.strptime ignores time zones, so we must use datetime.strptime()
+
+        # strptime doesn't support anything other than standard locale names
+        # for days of the week, so handle the "Thur" abbreviation as a special
+        # case as defined in the spec as it is unambiguous.
+        adjusted_changelog_timestamp_string = re.sub(
+            r'^Thur,',
+            'Thu,',
+            changelog_timestamp_string,
+        )
+
+        acceptable_date_formats = [
+            '%a, %d %b %Y %H:%M:%S %z',  # standard
+            '%A, %d %b %Y %H:%M:%S %z',  # full day of week
+            '%d %b %Y %H:%M:%S %z',      # missing day of week
+            '%a, %d %B %Y %H:%M:%S %z',  # full month name
+            '%A, %d %B %Y %H:%M:%S %z',  # full day of week and month name
+            '%d %B %Y %H:%M:%S %z',      # missing day of week with full month
+                                         # name
+        ]
+        for date_format in acceptable_date_formats:
+            try:
+                return datetime.datetime.strptime(
+                    adjusted_changelog_timestamp_string,
+                    date_format,
+                )
+            except ValueError:
+                pass
+        else:
+            raise ValueError(
+                "Could not parse date %r" % changelog_timestamp_string,
+            )
+
+    def git_authorship(self, author_date=None):
+        """Extract last changelog entry's maintainer and timestamp
+
+        Parse the first changelog entry's sign-off line into git's commit
+        authorship metadata model according to the import specification.
+
+        :param datetime.datetime author_date: overrides the author date
+            normally parsed from the changelog entry (i.e. for handling date
+            parsing edge cases). Any sub-second part of the timestamp is
+            truncated.
+        :rtype: tuple(str, str, int, int)
+        :returns: tuple of name, email, time (in seconds since epoch) and
+            offset from UTC (in minutes)
+        :raises ValueError: if the changelog sign-off line cannot be parsed
+        """
+        m = re.match(r'(?P<name>.*)<+(?P<email>.*?)>+', self.maintainer)
+        if m is None:
+            raise ValueError('Cannot get authorship')
+
+        author_epoch_seconds, author_tz_offset = datetime_to_signature_spec(
+            self._parse_changelog_date(self.date)
+            if author_date is None
+            else author_date
+        )
+
+        return (
+            # If the author name is empty, then it must be
+            # EMPTY_GIT_AUTHOR_NAME because git will not accept an empty author
+            # name. See the specification for details.
+            (
+                m.group('name').strip()
+                or gitubuntu.spec.EMPTY_GIT_AUTHOR_NAME
+            ),
+            m.group('email'),
+            author_epoch_seconds,
+            author_tz_offset,
+        )
+
+
+class GitUbuntuChangelogError(Exception):
+    pass
+
+class PristineTarError(Exception):
+    pass
+
+class PristineTarNotFoundError(PristineTarError):
+    pass
+
+class MultiplePristineTarFoundError(PristineTarError):
+    pass
+
+
+def git_dep14_tag(version):
+    """Munge a version string according to http://dep.debian.net/deps/dep14/"""
+    version = str(version)
+    version = version.replace('~', '_')
+    version = version.replace(':', '%')
+    version = version.replace('..', '.#.')
+    if version.endswith('.'):
+        version = version + '#'
+    if version.endswith('.lock'):
+        pre, _, _ = version.partition('.lock')
+        version = pre + '.#lock'
+    return version
+
+def import_tag(version, namespace, patch_state=PatchState.UNAPPLIED):
+    return '%s/%s/%s' % (
+        namespace,
+        {
+            PatchState.UNAPPLIED: 'import',
+            PatchState.APPLIED: 'applied',
+        }[patch_state],
+        git_dep14_tag(version),
+    )
+
+def reimport_tag_prefix(version, namespace, patch_state=PatchState.UNAPPLIED):
+    return '%s/reimport/%s/%s' % (
+        namespace,
+        {
+            PatchState.UNAPPLIED: 'import',
+            PatchState.APPLIED: 'applied',
+        }[patch_state],
+        git_dep14_tag(version),
+    )
+
+def reimport_tag(
+    version,
+    namespace,
+    reimport,
+    patch_state=PatchState.UNAPPLIED,
+):
+    return '%s/%s' % (
+        reimport_tag_prefix(version, namespace, patch_state=patch_state),
+        reimport,
+    )
+
+def upload_tag(version, namespace):
+    return '%s/upload/%s' % (namespace, git_dep14_tag(version))
+
+def upstream_tag(version, namespace):
+    return '%s/upstream/%s' % (namespace, git_dep14_tag(version))
+
+def orphan_tag(version, namespace):
+    return '%s/orphan/%s' % (namespace, git_dep14_tag(version))
+
+def is_dir_3_0_quilt(_dir=None):
+    _dir = _dir if _dir else '.'
+    try:
+        fmt, _ = run(['dpkg-source', '--print-format', _dir])
+        if '3.0 (quilt)' in fmt:
+            return True
+    except CalledProcessError as e:
+        try:
+            with open(os.path.join(_dir, 'debian/source/format'), 'r') as f:
+                for line in f:
+                     if re.match(r'3.0 (.*)', line):
+                         return True
+        # `man dpkg-source` indicates no d/s/format implies 1.0
+        except OSError:
+            pass
+
+    return False
+
+def is_3_0_quilt(repo, commitish='HEAD'):
+    with repo.temporary_worktree(commitish):
+       return is_dir_3_0_quilt()
+
+class GitUbuntuRepositoryFetchError(Exception):
+    pass
+
+
+def determine_quilt_series_path(pygit2_repo, treeish_obj):
+    """Find the active quilt series file path in use.
+
+    Look in the given tree for the Debian patch series file that is active
+    according to the search algorithm described in dpkg-source(1). If none are
+    found, return the default series path (again from dpkg-source(1)).
+
+    :param pygit2.Repo pygit2_repo: repository to look in.
+    :param pygit2.Object treeish_obj: object that peels to a pygit2.Tree.
+    :returns: relative path to series file.
+    :rtype: str
+    """
+    for series_name in ['debian.series', 'series']:
+        try:
+            series_path = posixpath.join('debian/patches', series_name)
+            blob = follow_symlinks_to_blob(
+                repo=pygit2_repo,
+                treeish_object=treeish_obj,
+                path=series_path,
+            )
+        except KeyError:
+            continue  # try the next path using our search list
+        return series_path  # series file blob found at this path
+
+    logging.debug("Unable to find a series file in %r", treeish_obj)
+    return 'debian/patches/series'  # default when no series file found
+
+
+def quilt_env(pygit2_repo, treeish):
+    """Find the appropriate quilt environment to use.
+
+    Return the canonical environment that should be used when calling quilt.
+    Since the series file doesn't necessarily always have the same name, a
+    source tree is examined to determine the name and set QUILT_SERIES
+    appropriately.
+
+    This does not integrate any other environment variables. Only environment
+    variables that influence quilt are returned.
+
+    :param pygit2.Repo pygit2_repo: repository to look in.
+    :param pygit2.Object treeish: object that peels to a pygit2.Tree.
+    :returns: quilt-specific environment settings
+    :rtype: dict
+    """
+    return {
+        'QUILT_PATCHES': 'debian/patches',
+        'QUILT_SERIES': determine_quilt_series_path(pygit2_repo, treeish),
+        'QUILT_NO_DIFF_INDEX': '1',
+        'QUILT_NO_DIFF_TIMESTAMPS': '1',
+        'EDITOR': 'true',
+    }
+
+
+def datetime_to_signature_spec(datetime):
+    """Convert a datetime to the time and offset required by a pygit2.Signature
+
+    :param datetime datetime: the timezone-aware datetime to convert
+    :rtype: tuple(int, int)
+    :returns: the time since epoch and timezone offset in minutes as suitable
+        for passing to the pygit2.Signature constructor parameters time and
+        offset.
+    """
+    # Divide by 60 for seconds -> minutes
+    offset_td = datetime.utcoffset()
+    offset_mins = (
+        int(offset_td.total_seconds()) // 60
+        if offset_td
+        else 0
+    )
+
+    return int(datetime.timestamp()), offset_mins
+
+
+class HeadInfoItem(collections.namedtuple(
+    'HeadInfoItem',
+    [
+        'version',
+        'commit_time',
+        'commit_id',
+    ],
+)):
+    """Information associated with a single branch head
+
+    :ivar str version: the package version found in debian/changelog at the
+        branch head.
+    :ivar int commit_time: the timestamp of the commit at the branch head,
+        expressed as seconds since the Unix epoch.
+    :ivar pygit2.Oid commit_id: the hash of the commit at the branch head.
+    """
+    pass
+
+
+class GitUbuntuRepository:
+    """A class for interacting with an importer git repository
+
+    This class attempts to put all objects it manipulates in an
+    'importer/' namespace. It also uses tags in one of three namespaces:
+    'import/' for successfully imported published versions (these are
+    created by the importer); 'upload/' for uploaded version by Ubuntu
+    developers (these are understood by the importer and are aliased by
+    import/ tags when succesfully imported); and 'orphan/' for published
+    versions for which no parents can be found (these are also created
+    by the importer).
+
+    To access the underlying pygit2.Repository object, use the raw_repo
+    property.
+    """
+
+    def __init__(
+        self,
+        local_dir,
+        lp_user=None,
+        fetch_proto=None,
+        delete_on_close=True,
+    ):
+        """
+        If fetch_proto is None, the default value from
+        gitubuntu.__main__ will be used (top_level_defaults.proto).
+        """
+        if local_dir is None:
+            self._local_dir = tempfile.mkdtemp()
+        else:
+            local_dir = os.path.abspath(local_dir)
+            try:
+                os.mkdir(local_dir)
+            except FileExistsError:
+                local_dir_list = os.listdir(local_dir)
+                if local_dir_list and os.getenv(
+                    'GIT_DIR',
+                    '.git',
+                ) not in local_dir_list:
+                    logging.error('Specified directory %s must either '
+                                  'be empty or have been previously '
+                                  'imported to.', local_dir)
+                    sys.exit(1)
+            self._local_dir = local_dir
+
+        self.raw_repo = pygit2.init_repository(self._local_dir)
+        # We rely on raw_repo.workdir to be identical to self._local_dir to
+        # avoid changing previous behaviour in the setting of GIT_WORK_TREE, so
+        # assert that it is so. This may not be the case if the git repository
+        # has a different workdir stored in its configuration or if the git
+        # repository is a bare repository. We didn't handle these cases before
+        # anyway, so with this assertion we can fail noisily and early.
+        assert (
+            os.path.normpath(self.raw_repo.workdir) ==
+                os.path.normpath(self._local_dir)
+        )
+
+        # Since previous behaviour of this class depended on the state of the
+        # environment at the time it was constructed, save this for later use
+        # (for example in deriving the environment to use for calls to the git
+        # CLI). This permits the behaviour to remain identical for now.
+        # Eventually we can break previous behaviour and eliminate the need for
+        # this. See also: gitubuntu.test_fixtures.repo; the handling of EMAIL
+        # there could be made cleaner when this is cleaned up.
+        self._initial_env = os.environ.copy()
+
+        self.set_git_attributes()
+
+        if lp_user:
+            self._lp_user = lp_user
+        else:
+            try:
+                self._lp_user, _ = self.git_run(
+                    ['config', 'gitubuntu.lpuser'],
+                    verbose_on_failure=False,
+                )
+                self._lp_user = self._lp_user.strip()
+            except CalledProcessError:
+                self._lp_user = None
+
+        if fetch_proto is None:
+            fetch_proto = top_level_defaults.proto
+
+        self._fetch_proto = fetch_proto
+        self._delete_on_close = delete_on_close
+
+    def close(self):
+        """Free resources associated with this instance
+
+        If delete_on_close was True on instance construction, local_dir (as
+        specified on instance construction) will be deleted.
+
+        After this method is called, the instance is invalid and can no longer
+        be used.
+        """
+        if self.raw_repo and self._delete_on_close:
+            shutil.rmtree(self.local_dir)
+        self.raw_repo = None
+
+    def create_orphan_branch(self, branch_name, msg):
+        if self.get_head_by_name(branch_name) is None:
+            self.git_run(['checkout', '--orphan', branch_name])
+            self.git_run(['commit', '--allow-empty', '-m', msg])
+            self.git_run(['checkout', '--orphan', 'master'])
+
+    @contextmanager
+    def pristine_tar_branches(self, dist, namespace='pkg', create=True):
+        """Context manager wrapping pristine-tar branch manipulation
+
+        In this context, the repository pristine-tar branch will point to
+        the pristine-tar branch for @dist distribution in @namespace.
+
+        Because of our model, the distribution-pristine-tar branch may
+        be a local branch (import-time) or a remote-tracking branch
+        (build-time) and we need different behavior in both cases.
+        Specifically, we want to affect the local branch's contents, but
+        we cannot do that to a remote-tracking branch.
+
+        Upon entry to the context, detect the former case (by doing a
+        local only lookup first) and doing a branch rename there.
+        Otherwise, create a new local branch.
+
+        Upon exit, if a local branch had been found, rename pristine-tar
+        back to the original name. Otherwise, simply delete the created
+        pristine-tar branch.
+
+        If a local branch named pristine-tar existed outside this
+        context, it will be restored upon leaving the context.
+
+        :param dist str One of 'ubuntu' or 'debian'
+        :param namespace str Namespace under which Git refs are found
+        :param create bool If an appropriate local pristine-tar Git
+             branch does not exist, create one using the above algorithm.
+        """
+        pt_branch = '%s/importer/%s/pristine-tar' % (namespace, dist)
+        old_pt_branch = self.raw_repo.lookup_branch('pristine-tar')
+        old_pt_branch_commit = None
+        if old_pt_branch:
+            old_pt_branch_commit = old_pt_branch.peel(pygit2.Commit)
+            old_pt_branch.delete()
+        local_pt_branch = self.raw_repo.lookup_branch(pt_branch)
+        remote_pt_branch = self.raw_repo.lookup_branch(
+            pt_branch,
+            pygit2.GIT_BRANCH_REMOTE,
+        )
+        if local_pt_branch:
+            local_pt_branch.rename('pristine-tar')
+        elif remote_pt_branch:
+            self.raw_repo.create_branch(
+                'pristine-tar',
+                remote_pt_branch.peel(pygit2.Commit),
+            )
+        elif create:
+            # This should only be possible when importing and the first
+            # pristine-tar usage, create an orphan branch at the local
+            # pt branch location and flag it for cleanup
+            local_pt_branch = True
+            self.create_orphan_branch(
+                'pristine-tar',
+                'Initial %s pristine-tar branch.' % dist,
+            )
+            if not self.raw_repo.lookup_branch('do-not-push'):
+                self.create_orphan_branch(
+                    'do-not-push',
+                    'Initial upstream branch.',
+                )
+        try:
+            yield
+        except:
+            raise
+        finally:
+            if local_pt_branch: # or create above
+                self.raw_repo.lookup_branch('pristine-tar').rename(pt_branch)
+            elif remote_pt_branch:
+                self.raw_repo.lookup_branch('pristine-tar').delete()
+            if old_pt_branch_commit:
+                self.raw_repo.create_branch(
+                    'pristine-tar',
+                    old_pt_branch_commit,
+                )
+
+    def pristine_tar_list(self, dist, namespace='pkg'):
+        """List tarballs stored in pristine-tar branch for @dist distribution in @namespace.
+
+        If there is no pristine-tar branch, `pristine-tar list` returns
+        nothing.
+
+        :param dist str One of 'ubuntu' or 'debian'
+        :param namespace str Namespace under which Git refs are found
+        :rtype list(str)
+        :returns List of orig tarball names stored in the pristine-tar
+             branches
+        """
+        with self.pristine_tar_branches(dist, namespace, create=False):
+            stdout, _ = run(['pristine-tar', 'list'])
+            return stdout.strip().splitlines()
+
+    def pristine_tar_extract(self, pkgname, version, dist=None, namespace='pkg'):
+        '''Extract orig tarballs for a given package and upstream version
+
+        This function will fail if the expected tarballs are already
+        present by name in the parent directory. If, at some point, this
+        is not desired, we would need to pass --git-force-create to
+        gbp-buildpackage.
+
+        The files, once created, are the responsibility of the caller to
+        remove, if necessary.
+
+        raises:
+        - PristineTarNotFoundError if no suitable tarballs are found
+        - MultiplePristineTarFoundError if multiple distinct suitable tarballs
+          are found
+        - CalledProcessError if gbp-buildpackage fails
+
+        :param pkgname str Source package name
+        :param version str Source package upstream version
+        :param dist str One of 'ubuntu' or 'debian'
+        :param namespace str Namespace under which Git refs are found
+        :rtype list(str)
+        :returns List of tarball paths that are now present on the
+            filesystem. They will be in the parent directory.
+        '''
+        dists = [dist] if dist else ['debian', 'ubuntu']
+        for dist in dists:
+            main_tarball = '%s_%s.orig.tar' % (pkgname, version)
+
+            all_tarballs = self.pristine_tar_list(dist, namespace)
+
+            potential_main_tarballs = [tarball for tarball
+                in all_tarballs if tarball.startswith(main_tarball)]
+            if len(potential_main_tarballs) == 0:
+                continue
+            if len(potential_main_tarballs) > 1:
+                # This will need some extension/flag for the case of there
+                # being multiple imports with varying compression
+                raise MultiplePristineTarFoundError(
+                    'More than one pristine-tar tarball found for %s: %s' %
+                    (version, potential_main_tarballs)
+                )
+            ext = os.path.splitext(potential_main_tarballs[0])[1]
+            tarballs = []
+            tarballs.append(
+                os.path.join(os.path.pardir, potential_main_tarballs[0])
+            )
+            args = ['buildpackage', '--git-builder=/bin/true',
+                   '--git-pristine-tar', '--git-ignore-branch',
+                   '--git-upstream-tag=%s/upstream/%s/%%(version)s%s' %
+                   (namespace, dist, ext)]
+            # This will probably break if the component tarballs get
+            # compressed differently, as each component tarball will show up
+            # multiple times
+            # Breaks may be too strong -- we will 'over cache' tarballs, and
+            # then it's up to dpkg-buildpackage to use the 'correct' one
+            potential_component_tarballs = {
+                component_tarball_matches(tarball, pkgname, version).group('component') : tarball
+                for tarball in all_tarballs
+                if component_tarball_matches(tarball, pkgname, version)
+            }
+            tarballs.extend(map(lambda x : os.path.join(os.path.pardir, x),
+                list(potential_component_tarballs.values()))
+            )
+            args.extend(map(lambda x : '--git-component=%s' % x,
+                list(potential_component_tarballs.keys()))
+            )
+            with self.pristine_tar_branches(dist, namespace):
+                run_gbp(args, env=self.env)
+            return tarballs
+
+        raise PristineTarNotFoundError(
+            'No pristine-tar tarball found for %s' % version
+        )
+
+    def pristine_tar_exists(self, pkgname, version, namespace='pkg'):
+        '''Report distributions that contain pristine-tar data for @version
+
+        raises:
+        - MultiplePristineTarFoundError if multiple distinct suitable tarballs
+          are found
+
+        :param pkgname str Source package name
+        :param version str Source package upstream version
+        :param namespace str Namespace under which Git refs are found
+        :rtype list(str)
+        :returns List of distribution names which contain a pristine-tar
+             import for @pkgname and @version
+        '''
+        results = []
+        for dist in ['debian', 'ubuntu']:
+            main_tarball = '%s_%s.orig.tar' % (pkgname, version)
+
+            all_tarballs = self.pristine_tar_list(dist, namespace)
+
+            potential_main_tarballs = [tarball for tarball
+                in all_tarballs if tarball.startswith(main_tarball)]
+            if len(potential_main_tarballs) == 0:
+                continue
+            if len(potential_main_tarballs) > 1:
+                # This will need some extension/flag for the case of there
+                # being multiple imports with varying compression
+                raise MultiplePristineTarFoundError(
+                    'More than one pristine-tar tarball found for %s: %s' %
+                    (version, potential_main_tarballs)
+                )
+            results.append(dist)
+
+        return results
+
+    def verify_pristine_tar(self, tarball_paths, dist, namespace='pkg'):
+        '''Verify the pristine-tar data matches for a set of paths
+
+        raises:
+             PristineTarError - if a tarball has been imported before,
+             but the contents of the new tarball do not match
+
+        :param tarball_paths list(str) List of filesystem paths of orig
+             tarballs to verify
+        :param dist str One of 'ubuntu' or 'debian'
+        :param namespace str Namespace under which Git refs are found
+        :rtype bool
+        :returns True if all paths in @tarball_paths exist in @dist's
+             pristine-tar branch under @namespace and match the
+             corresponding pristine-tar contents exactly
+        '''
+        all_tarballs = self.pristine_tar_list(dist, namespace)
+        for path in tarball_paths:
+            if os.path.basename(path) not in all_tarballs:
+                break
+            try:
+                with self.pristine_tar_branches(dist, namespace):
+                    # need to handle this not existing
+                    run(['pristine-tar', 'verify', path])
+            except CalledProcessError as e:
+                raise PristineTarError(
+                    'Tarball has already been imported to %s with '
+                    'different contents' % dist
+                )
+        else:
+            return True
+
+        return False
+
+    def set_git_attributes(self):
+        git_attr_path = os.path.join(self.raw_repo.path,
+                                     'info',
+                                     'attributes'
+                                    )
+        try:
+            # common-case: create an attributes file
+            with open(git_attr_path, 'x') as f:
+                f.write('* -ident\n')
+                f.write('* -text\n')
+                f.write('* -eol\n')
+        except FileExistsError:
+            # next-most common-case: attributes file already exists and
+            # contains our desired value
+            try:
+                runq(['grep', '-q', '* -ident', git_attr_path])
+            except CalledProcessError:
+                # least-common case: attributes file exists, but does
+                # not contain our desired value
+                try:
+                    with open(git_attr_path, 'a') as f:
+                        f.write('* -ident\n')
+                except:
+                    # failed all three cases to set our desired value in
+                    # attributes file
+                    logging.exception('Unable to set \'* -ident\' in %s' %
+                                      git_attr_path
+                                     )
+                    sys.exit(1)
+            try:
+                runq(['grep', '-q', '* -text', git_attr_path])
+            except CalledProcessError:
+                # least-common case: attributes file exists, but does
+                # not contain our desired value
+                try:
+                    with open(git_attr_path, 'a') as f:
+                        f.write('* -text\n')
+                except:
+                    # failed all three cases to set our desired value in
+                    # attributes file
+                    logging.exception('Unable to set \'* -text\' in %s' %
+                                      git_attr_path
+                                     )
+                    sys.exit(1)
+            try:
+                runq(['grep', '-q', '* -eol', git_attr_path])
+            except CalledProcessError:
+                # least-common case: attributes file exists, but does
+                # not contain our desired value
+                try:
+                    with open(git_attr_path, 'a') as f:
+                        f.write('* -eol\n')
+                except:
+                    # failed all three cases to set our desired value in
+                    # attributes file
+                    logging.exception('Unable to set \'* -eol\' in %s' %
+                                      git_attr_path
+                                     )
+                    sys.exit(1)
+
+    def remote_exists(self, remote_name):
+        # https://github.com/libgit2/pygit2/issues/671
+        return any(remote.name == remote_name for remote in self.raw_repo.remotes)
+
+    def _add_remote_by_fetch_url(
+        self,
+        remote_name,
+        fetch_url,
+        push_url=None,
+        changelog_notes=False,
+    ):
+        """Add a remote by URL
+
+        If a remote with the given name doesn't exist, then create it.
+        Otherwise, do nothing.
+
+        :param str remote_name: the name of the remote to create
+        :param str fetch_url: the fetch URL for the remote
+        :param str push_url: the push URL for the remote. If None, then a
+            specific push URL will not be set.
+        :param bool changelog_notes: if True, then a fetch refspec will be
+            added to fetch changelog notes. This only makes sense for an
+            official importer remote such as 'pkg'.
+        :returns: None
+        """
+        if not self._fetch_proto:
+            raise Exception('Cannot fetch using an object without a protocol')
+
+        logging.debug('Adding %s as remote %s', fetch_url, remote_name)
+
+        if not self.remote_exists(remote_name):
+            self.raw_repo.remotes.create(
+                remote_name,
+                fetch_url,
+                '+refs/heads/*:refs/remotes/%s/*' % remote_name,
+            )
+            # grab unreachable tags (orphans)
+            self.raw_repo.remotes.add_fetch(
+                remote_name,
+                '+refs/tags/*:refs/tags/%s/*' % remote_name,
+            )
+            if changelog_notes:
+                # The changelog notes are kept at refs/notes/commits on
+                # Launchpad due to LP: #1871838 even though our standard place
+                # for them is refs/notes/changelog.
+                self.raw_repo.remotes.add_fetch(
+                    remote_name,
+                    '+refs/notes/commits:refs/notes/changelog',
+                )
+            if push_url:
+                self.raw_repo.remotes.set_push_url(
+                    remote_name,
+                    push_url,
+                )
+            self.git_run(
+                [
+                     'config',
+                     'remote.%s.tagOpt' % remote_name,
+                     '--no-tags',
+                ]
+            )
+
+    def _add_remote(self, remote_name, remote_url, changelog_notes=False):
+        """Add a remote by URL location
+
+        URL location means the part of the URL after the proto:// prefix. The
+        protocol to be used will be determined by what was specified by the
+        fetch_proto at class instance construction time. Separate fetch and
+        push URL protocols will be automatically determined.
+
+        If a remote with the given name doesn't exist, then create it.
+        Otherwise, do nothing.
+
+        :param str remote_name: the name of the remote to create
+        :param str remote_url: the URL for the remote but with the proto://
+            prefix missing.
+        :param bool changelog_notes: if True, then a fetch refspec will be
+            added to fetch changelog notes. This only makes sense for an
+            official importer remote such as 'pkg'.
+        :returns: None
+        """
+        if not self._fetch_proto:
+            raise Exception('Cannot fetch using an object without a protocol')
+        if not self._lp_user:
+            raise RuntimeError("Cannot add remote without knowing lp_user")
+        fetch_url = '%s://%s' % (self._fetch_proto, remote_url)
+        push_url = 'ssh://%s@%s' % (self.lp_user, remote_url)
+
+        self._add_remote_by_fetch_url(
+            remote_name=remote_name,
+            fetch_url=fetch_url,
+            push_url=push_url,
+            changelog_notes=changelog_notes,
+        )
+
+    def add_remote(
+        self,
+        pkgname,
+        repo_owner,
+        remote_name,
+        changelog_notes=False,
+    ):
+        """Add a remote to the repository configuration
+        :param str pkgname: the name of the source package reflected by this
+            repository.
+        :param str repo_owner: the name of the Launchpad user or team whose
+            repository for the package will be pointed to by this new remote.
+            If None, the default repository for the source package will be
+            used.
+        :param str remote_name: the name of the remote to add.
+        :param bool changelog_notes: if True, then a fetch refspec will be
+            added to fetch changelog notes. This only makes sense for an
+            official importer remote such as 'pkg'.
+        :returns: None
+        """
+        if not self._fetch_proto:
+            raise Exception('Cannot fetch using an object without a protocol')
+        if repo_owner:
+            remote_url = ('git.launchpad.net/~%s/ubuntu/+source/%s' %
+                          (repo_owner, pkgname))
+        else:
+            remote_url = ('git.launchpad.net/ubuntu/+source/%s' % pkgname)
+
+        self._add_remote(
+            remote_name=remote_name,
+            remote_url=remote_url,
+            changelog_notes=changelog_notes,
+        )
+
+    def add_remote_by_url(self, remote_name, fetch_url):
+        if not self._fetch_proto:
+            raise Exception('Cannot fetch using an object without a protocol')
+
+        self._add_remote_by_fetch_url(remote_name, fetch_url)
+
+    def add_base_remotes(self, pkgname, repo_owner=None):
+        """Add the 'pkg' base remote to the repository configuration
+
+        :param str pkgname: the name of the source package reflected by this
+            repository.
+        :param str repo_owner: the name of the Launchpad user or team whose
+            repository for the package will be pointed to by this new remote.
+            If None, the default repository for the source package will be
+            used.
+        :returns: None
+        """
+        self.add_remote(pkgname, repo_owner, 'pkg', changelog_notes=True)
+
+    def add_lpuser_remote(self, pkgname):
+        if not self._fetch_proto:
+            raise Exception('Cannot add a fetch using an object without a protocol')
+        if not self._lp_user:
+            raise RuntimeError("Cannot add remote without knowing lp_user")
+        remote_url = ('git.launchpad.net/~%s/ubuntu/+source/%s' %
+                      (self.lp_user, pkgname))
+
+        self._add_remote(remote_name=self.lp_user, remote_url=remote_url)
+        # XXX: want a remote alias of 'lpme' -> self.lp_user
+        # self.git_run(['config', 'url.%s.insteadof' % self.lp_user, 'lpme'])
+
+    def fetch_remote(self, remote_name, verbose=False):
+        # Does not seem to be working with https
+        # https://github.com/libgit2/pygit2/issues/573
+        # https://github.com/libgit2/libgit2/issues/3786
+        # self.raw_repo.remotes[remote_name].fetch()
+        kwargs = {}
+        kwargs['verbose_on_failure'] = True
+        if verbose:
+            # If we are redirecting stdout/stderr to the console, we
+            # do not need to have run() also emit it
+            kwargs['verbose_on_failure'] = False
+            kwargs['stdout'] = None
+            kwargs['stderr'] = None
+        try:
+            logging.debug("Fetching remote %s", remote_name)
+            self.git_run(
+                args=['fetch', remote_name],
+                env={'GIT_TERMINAL_PROMPT': '0',},
+                **kwargs
+            )
+        except CalledProcessError:
+            raise GitUbuntuRepositoryFetchError(
+                "Unable to fetch remote %s" % remote_name
+            )
+
+    def fetch_base_remotes(self, verbose=False):
+        self.fetch_remote(remote_name='pkg', verbose=verbose)
+
+    def fetch_remote_refspecs(self, remote_name, refspecs, verbose=False):
+        # Does not seem to be working with https
+        # https://github.com/libgit2/pygit2/issues/573
+        # https://github.com/libgit2/libgit2/issues/3786
+        # self.raw_repo.remotes[remote_name].fetch()
+        for refspec in refspecs:
+            kwargs = {}
+            kwargs['verbose_on_failure'] = True
+            if verbose:
+                # If we are redirecting stdout/stderr to the console, we
+                # do not need to have run() also emit it
+                kwargs['verbose_on_failure'] = False
+                kwargs['stdout'] = None
+                kwargs['stderr'] = None
+            try:
+                logging.debug(
+                    "Fetching refspec %s from remote %s",
+                    refspec,
+                    remote_name,
+                )
+                self.git_run(
+                    args=['fetch', remote_name, refspec],
+                    env={'GIT_TERMINAL_PROMPT': '0',},
+                    **kwargs,
+                )
+            except CalledProcessError:
+                raise GitUbuntuRepositoryFetchError(
+                    "Unable to fetch %s from remote %s" % (
+                        refspecs,
+                        remote_name,
+                    )
+                )
+
+    def fetch_lpuser_remote(self, verbose=False):
+        if not self._fetch_proto:
+            raise Exception('Cannot fetch using an object without a protocol')
+        if not self._lp_user:
+            raise RuntimeError("Cannot fetch without knowing lp_user")
+        self.fetch_remote(remote_name=self.lp_user, verbose=verbose)
+
+    def copy_base_references(self, namespace):
+        for ref in self.references:
+            for (target_refs, source_refs) in [
+                ('refs/heads/%s/' % namespace, 'refs/remotes/pkg/'),]:
+                if ref.name.startswith(source_refs):
+                    self.raw_repo.create_reference(
+                        '%s/%s' % (target_refs, ref.name[len(source_refs):]),
+                        ref.peel().id)
+
+    def delete_branches_in_namespace(self, namespace):
+        _local_branches = copy(self.local_branches)
+        for head in self.local_branches:
+            if head.branch_name.startswith(namespace):
+                head.delete()
+
+    def delete_tags_in_namespace(self, namespace):
+        _tags = copy(self.tags)
+        for ref in self.tags:
+            if ref.name.startswith('refs/tags/%s' % namespace):
+                ref.delete()
+
+    @property
+    def env(self):
+        # Return a copy of the cached _derive_env method result so that the
+        # caller cannot inadvertently modify our cached answer. Unfortunately
+        # this leaks the lru_cache-ness of the _derive_env method to this
+        # property getter, but this seems better than nothing.
+        return dict(self._derive_env())
+
+    @lru_cache()
+    def _derive_env(self):
+        """Determine what the git CLI environment should be
+
+        This depends on the initial environment saved from the constructor and
+        the paths associated with self.raw_repo, neither of which should change
+        in the lifetime of this class instance.
+        """
+        return _derive_git_cli_env(
+            self.raw_repo,
+            initial_env=self._initial_env
+        )
+
+    @property
+    def local_dir(self):
+        """Base directory of this git repository (contains .git/)"""
+        return self._local_dir
+
+    @property
+    def git_dir(self):
+        """Same as cached object in the environment"""
+        return self.raw_repo.path
+
+    def _references(self, prefix=''):
+        return [self.raw_repo.lookup_reference(r) for r in
+                self.raw_repo.listall_references() if
+                r.startswith(prefix)]
+
+    def references_with_prefix(self, prefix):
+        return self._references(prefix)
+
+    @property
+    def references(self):
+        return self._references()
+
+    @property
+    def tags(self):
+        return self._references('refs/tags')
+
+    def _branches(self,
+                  branch_type=pygit2.GIT_BRANCH_LOCAL | pygit2.GIT_BRANCH_REMOTE):
+        branches = []
+        if branch_type & pygit2.GIT_BRANCH_LOCAL:
+            branches.extend([self.raw_repo.lookup_branch(b) for b in
+                self.raw_repo.listall_branches(pygit2.GIT_BRANCH_LOCAL)])
+        if branch_type & pygit2.GIT_BRANCH_REMOTE:
+            branches.extend([self.raw_repo.lookup_branch(b, pygit2.GIT_BRANCH_REMOTE) for b in
+                self.raw_repo.listall_branches(pygit2.GIT_BRANCH_REMOTE)])
+        return branches
+
+    @property
+    def branches(self):
+        return self._branches()
+
+    @property
+    def branch_names(self):
+        return [b.branch_name for b in self.branches]
+
+    @property
+    def local_branches(self):
+        return self._branches(pygit2.GIT_BRANCH_LOCAL)
+
+    @property
+    def local_branch_names(self):
+        return [b.branch_name for b in self.local_branches]
+
+    @property
+    def remote_branches(self):
+        return self._branches(pygit2.GIT_BRANCH_REMOTE)
+
+    @property
+    def remote_branch_names(self):
+        return [b.branch_name for b in self.remote_branches]
+
+    @property
+    def lp_user(self):
+        if not self._lp_user:
+            raise RuntimeError("lp_user is not set")
+        return self._lp_user
+
+    def get_commitish(self, commitish):
+        return self.raw_repo.revparse_single(commitish)
+
+    def head_to_commit(self, head_name):
+        return str(self.get_head_by_name(head_name).peel().id)
+
+    def get_short_hash(self, hash):
+        """Return an unambiguous but abbreviated form of a commit hash
+
+        Note that the hash may still become ambiguous in the future.
+        """
+        stdout, _ = self.git_run(['rev-parse', '--short', hash])
+        return stdout.strip()
+
+    def git_run(self, args, env=None, **kwargs):
+        """Run the git CLI with the provided arguments
+
+        :param list(str) args: arguments to the git CLI
+        :param dict env: additional environment variables to use
+        :param dict **kwargs: further arguments to pass through to
+            gitubuntu.run.run()
+        :raises subprocess.CalledProcessError: if git exits non-zero
+        :rtype: (str, str)
+        :returns: stdout and stderr strings containing the subprocess output
+
+        The environment used is based on the Python process' environment at the
+        time this class instance was constructed.
+
+        The GIT_DIR and GIT_WORK_TREE environment variables are set
+        automatically based on the repository's existing location and settings.
+
+        If env is set, then the environment to be used is updated with env
+        before the call to git is made. This can override GIT_DIR,
+        GIT_WORK_TREE, and anything else.
+        """
+        return git_run(
+            pygit2_repo=self.raw_repo,
+            args=args,
+            initial_env=self._initial_env,
+            update_env=env,
+            **kwargs,
+        )
+
+    def garbage_collect(self):
+        self.git_run(['gc'])
+
+    def extract_file_from_treeish(self, treeish_string, filename):
+        """extract a file from @treeish to a local file
+
+        Arguments:
+        treeish - SHA1 of treeish
+        filename - file to extract from @treeish
+
+        Returns a NamedTemporaryFile that is flushed but not rewound.
+        """
+        blob = follow_symlinks_to_blob(
+            self.raw_repo,
+            treeish_object=self.raw_repo.revparse_single(treeish_string),
+            path=filename,
+        )
+        outfile = tempfile.NamedTemporaryFile()
+        outfile.write(blob.data)
+        outfile.flush()
+        return outfile
+
+    @lru_cache()
+    def get_changelog_from_treeish(self, treeish_string):
+        return Changelog.from_treeish(
+            self.raw_repo,
+            self.raw_repo.revparse_single(treeish_string),
+        )
+
+    def get_changelog_versions_from_treeish(self, treeish_string):
+        """Extract current and prior versions from debian/changelog in a
+        given @treeish_string
+
+        Returns (None, None) if the treeish supplied is None or if
+        'debian/changelog' does not exist in the treeish.
+
+        Returns (current, previous) on success.
+        """
+        try:
+            changelog = self.get_changelog_from_treeish(treeish_string)
+        except KeyError:
+            # If 'debian/changelog' does
+            # not exist, then (None, None) is returned. KeyError propagates up
+            # from Changelog's __init__.
+            return None, None
+        try:
+            return changelog.version, changelog.previous_version
+        except CalledProcessError:
+            raise GitUbuntuChangelogError(
+                'Cannot get changelog versions'
+            )
+
+    def get_changelog_distribution_from_treeish(self, treeish_string):
+        """Extract targetted distribution from debian/changelog in a
+        given treeish
+        """
+
+        if treeish_string is None:
+            return None
+
+        try:
+            return self.get_changelog_from_treeish(treeish_string).distribution
+        except (KeyError, CalledProcessError):
+            raise GitUbuntuChangelogError(
+                'Cannot get changelog distribution'
+            )
+
+    def get_changelog_srcpkg_from_treeish(self, treeish_string):
+        """Extract srcpkg from debian/changelog in a given treeish
+        """
+
+        if treeish_string is None:
+            return None
+
+        try:
+            return self.get_changelog_from_treeish(treeish_string).srcpkg
+        except (KeyError, CalledProcessError):
+            raise GitUbuntuChangelogError(
+                'Cannot get changelog source package name'
+            )
+
+    def get_head_info(self, head_prefix, namespace):
+        """Extract package versions at branch heads
+
+        Extract the version from debian/changelog of all
+        f'{namespace}/{head_prefix>/*' branches, excluding any branch that
+        contains 'ubuntu/devel'.
+
+        :param str namespace: the namespace under which git refs are found
+        :param str head_prefix: the prefix to look for
+        :rtype: dict(str, HeadInfoItem)
+        :returns: a dictionary keyed by the namespaced branch name (ie. without
+            a 'refs/heads/' prefix but with the namespace prefix, eg.
+            'importer/ubuntu/focal-devel').
+        """
+        head_info = dict()
+        for head in self.local_branches:
+            prefix = '%s/%s' % (namespace, head_prefix)
+            if not head.branch_name.startswith(prefix):
+                continue
+            if 'ubuntu/devel' in head.branch_name:
+                continue
+            version, _ = (
+                self.get_changelog_versions_from_treeish(str(head.peel().id))
+            )
+            head_info[head.branch_name] = HeadInfoItem(
+                version=version,
+                commit_time=head.peel().commit_time,
+                commit_id=head.peel().id,
+            )
+
+        return head_info
+
+    def treeishs_identical(self, treeish_string1, treeish_string2):
+        if treeish_string1 is None or treeish_string2 is None:
+            return False
+        _tree_obj1 = self.raw_repo.revparse_single(treeish_string1)
+        _tree_id1 = _tree_obj1.peel(pygit2.Tree).id
+        _tree_obj2 = self.raw_repo.revparse_single(treeish_string2)
+        _tree_id2 = _tree_obj2.peel(pygit2.Tree).id
+        return _tree_id1 == _tree_id2
+
+    def get_head_by_name(self, name):
+        try:
+            return self.raw_repo.lookup_branch(name)
+        except TypeError:
+            return None
+
+    def get_tag_reference(self, tag):
+        """Return the tag object if it exists in the repository"""
+        try:
+            return self.raw_repo.lookup_reference('refs/tags/%s' % tag)
+        except (KeyError, ValueError):
+            return None
+
+    def get_import_tag(
+        self,
+        version,
+        namespace,
+        patch_state=PatchState.UNAPPLIED,
+    ):
+        """
+        Return the import tag matching the given specification.
+
+        :param str version: the package version string to match
+        :param str namespace: the namespace under which git refs are found
+        :param PatchState patch_state: whether to look for unapplied or applied
+            tags
+        :returns: the matching import tag, or None if there is no match
+        :rtype: pygit2.Reference or None
+        """
+        return self.get_tag_reference(
+            import_tag(version, namespace, patch_state)
+        )
+
+    def get_reimport_tag(
+        self,
+        version,
+        namespace,
+        reimport,
+        patch_state=PatchState.UNAPPLIED,
+    ):
+        """
+        Return the reimport tag matching the given specification.
+
+        :param str version: the package version string to match
+        :param str namespace: the namespace under which git refs are found
+        :param int reimport: the sequence number of the reimport tag
+        :param PatchState patch_state: whether to look for unapplied or applied
+            tags
+        :returns: the matching reimport tag, or None if there is no match
+        :rtype: pygit2.Reference or None
+        """
+        return self.get_tag_reference(
+            reimport_tag(version, namespace, reimport, patch_state)
+        )
+
+    def get_all_reimport_tags(
+        self,
+        version,
+        namespace,
+        patch_state=PatchState.UNAPPLIED,
+    ):
+        """
+        Return all reimport tags matching the given specification.
+
+        :param str version: the package version string to match
+        :param str namespace: the namespace under which git refs are found
+        :param PatchState patch_state: whether to look for unapplied or applied
+            tags
+        :returns: matching reimport tags
+        :rtype: sequence(pygit2.Reference)
+        """
+        return self.references_with_prefix(
+            'refs/tags/%s/' % reimport_tag_prefix(
+                version,
+                namespace,
+                patch_state,
+            )
+        )
+
+    def get_upload_tag(self, version, namespace):
+        """
+        Return the upload tag matching the given specification.
+
+        :param str version: the package version string to match
+        :param str namespace: the namespace under which git refs are found
+        :returns: the matching upload tag, or None if there is no match
+        :rtype: pygit2.Reference or None
+        """
+        return self.get_tag_reference(upload_tag(version, namespace))
+
+    def get_upstream_tag(self, version, namespace):
+        """
+        Return the upstream tag matching the given specification.
+
+        :param str version: the package version string to match
+        :param str namespace: the namespace under which git refs are found
+        :returns: the matching upstream tag, or None if there is no match
+        :rtype: pygit2.Reference or None
+        """
+        return self.get_tag_reference(upstream_tag(version, namespace))
+
+    def get_orphan_tag(self, version, namespace):
+        """
+        Return the orphan tag matching the given specification.
+
+        :param str version: the package version string to match
+        :param str namespace: the namespace under which git refs are found
+        :returns: the matching orphan tag, or None if there is no match
+        :rtype: pygit2.Reference or None
+        """
+        return self.get_tag_reference(orphan_tag(version, namespace))
+
+    def create_tag(self,
+        commit_hash,
+        tag_name,
+        tag_msg,
+        tagger=None,
+    ):
+        """Create a tag in the repository
+
+        :param str commit_hash: the commit hash the tag will point to.
+        :param str tag_name: the name of the tag to be created.
+        :param str tag_msg: the text of the tag annotation.
+        :param pygit2.Signature tagger: if supplied, use this signature in the
+            created tag's "tagger" metadata. If not supplied, an arbitrary name
+            and email address is used with the current time.
+        :returns: None
+        """
+        if not tagger:
+            tagger_time, tagger_offset = datetime_to_signature_spec(
+                datetime.datetime.now(),
+            )
+            tagger = pygit2.Signature(
+               gitubuntu.spec.SYNTHESIZED_COMMITTER_NAME,
+               gitubuntu.spec.SYNTHESIZED_COMMITTER_EMAIL,
+               tagger_time,
+               tagger_offset,
+            )
+
+        logging.debug("Creating tag %s pointing to %s", tag_name, commit_hash)
+        self.raw_repo.create_tag(
+            tag_name,
+            pygit2.Oid(hex=commit_hash),
+            pygit2.GIT_OBJ_COMMIT,
+            tagger,
+            tag_msg,
+        )
+
+    def nearest_remote_branches(self, commit_hash, prefix=None,
+        max_commits=100
+    ):
+        '''Return the set of remote branches nearest to @commit_hash
+
+        This is a set of remote branch objects that are currently
+        pointing at a commit, where that commit is the nearest ancestor
+        to @commit_hash among the possible commits.
+
+        If no such commit is found, an empty set is returned.
+
+        Only consider remote branches that start with @prefix.
+
+        Stop searching beyond the @max_commits'-th ancestor. Usually this method
+        is only used as a heuristic that generally will never need to go too far
+        back in history, and this avoids searching all the way back to the root
+        commit, which may be a long way.
+        '''
+
+        # 1) cache all prefixed branch names by commit
+        remote_heads_by_commit = collections.defaultdict(set)
+        for b in self.remote_branches:
+            if prefix is None or b.branch_name.startswith(prefix):
+                remote_heads_by_commit[b.peel().id].add(b)
+
+        # 2) walk from commit_hash backwards until a cached commit is found
+        commits = self.raw_repo.walk(
+            self.get_commitish(commit_hash).id,
+            pygit2.GIT_SORT_TOPOLOGICAL,
+        )
+        for commit in itertools.islice(commits, max_commits):
+            if commit.id not in remote_heads_by_commit:
+                continue  # avoid creating a bunch of empty sets
+
+            if remote_heads_by_commit[commit.id]:
+                return remote_heads_by_commit[commit.id]
+
+            # in the currently impossible (but permitted in this state) case
+            # that the dictionary returned an empty set, we loop around again
+            # which is what we want.
+
+        return set()
+
+
+    def nearest_tag(
+        self,
+        commitish_string,
+        prefix,
+        max_commits=100,
+    ):
+        # 1) cache all patterned tag names by commit
+        pattern_tags_by_commit = collections.defaultdict(set)
+        for t in self.tags:
+            if t.name.startswith('refs/tags/' + prefix):
+                pattern_tags_by_commit[t.peel(pygit2.Commit).id].add(t)
+
+        commits = self.raw_repo.walk(
+            self.get_commitish(commitish_string).id,
+            pygit2.GIT_SORT_TOPOLOGICAL,
+        )
+        for commit in itertools.islice(commits, max_commits):
+            if commit.id not in pattern_tags_by_commit:
+                continue
+
+            return pattern_tags_by_commit[commit.id].pop()
+
+        return None
+
+    @staticmethod
+    def tag_to_pretty_name(tag):
+        _, _, pretty_name = tag.name.partition('refs/tags/')
+        return pretty_name
+
+    def create_tracking_branch(self, branch_name, upstream_name, force=False):
+        return self.raw_repo.create_branch(
+            branch_name,
+            self.raw_repo.lookup_branch(
+                upstream_name,
+                pygit2.GIT_BRANCH_REMOTE
+            ).peel(pygit2.Commit),
+            force
+        )
+
+    def checkout_commitish(self, commitish):
+        # pygit2 checkout does not accept hashes
+        # https://github.com/libgit2/pygit2/issues/412
+        # self.raw_repo.checkout_tree(self.get_commitish(commitish))
+        self.git_run(['checkout', commitish])
+
+    def reset_commitish(self, commitish):
+        # pygit2 checkout does not accept hashes
+        # https://github.com/libgit2/pygit2/issues/412
+        # self.checkout_tree(self.get_commitish(commitish))
+        self.git_run(['reset', '--hard', commitish])
+
+    def update_head_to_commit(self, head_name, commit_hash):
+        try:
+            self.raw_repo.lookup_branch(head_name).set_target(commit_hash)
+        except AttributeError:
+            self.raw_repo.create_branch(head_name,
+                self.raw_repo.get(commit_hash)
+            )
+
+    def clean_repository_state(self):
+        """Cleanup working tree"""
+        runq(['git', 'checkout', '--orphan', 'master'],
+             check=False, env=self.env)
+        runq(['git', 'reset', '--hard'], env=self.env)
+        runq(['git', 'clean', '-f', '-d'], env=self.env)
+
+    def get_all_changelog_versions_from_treeish(self, treeish):
+        changelog = self.get_changelog_from_treeish(treeish)
+        return changelog.all_versions
+
+    def annotated_tag(self, tag_name, commitish, force, msg=None):
+        try:
+            args = ['tag', '-a', tag_name, commitish]
+            if force:
+                args += ['-f']
+            if msg is not None:
+                args += ['-m', msg]
+            self.git_run(args, stdin=None, stdout=None, stderr=None)
+            version, _ = self.get_changelog_versions_from_treeish(commitish)
+            logging.info('Created annotated tag %s for version %s' % (tag_name, version))
+        except:
+            logging.error('Unable to tag %s. Does it already exist (pass -f)?' %
+                          tag_name
+                         )
+            raise
+
+    def tag(self, tag_name, commitish, force):
+        try:
+            args = ['tag', tag_name, commitish]
+            if force:
+                args += ['-f']
+            self.git_run(args)
+            version, _ = self.get_changelog_versions_from_treeish(commitish)
+            logging.info('Created tag %s for version %s' % (tag_name, version))
+        except:
+            logging.error('Unable to tag %s. Does it already exist (pass -f)?' %
+                          tag_name
+                         )
+            raise
+
+    def commit_source_tree(
+        self,
+        tree,
+        parents,
+        log_message,
+        commit_date=None,
+        author_date=None,
+    ):
+        """Commit a git tree with appropriate parents and message
+
+        Given a git tree that contains a source package, create a matching
+        commit using metadata derived from the tree as required according to
+        the import specification.
+
+        Commit metadata elements that are not specified as derived from the
+        tree itself are required as parameters.
+
+        :param pygit2.Oid tree: reference to the git tree in this repository
+            that contains a debian/changelog file
+        :param list(pygit2.Oid) parents: parent commits of the commit to be
+            created
+        :param bytes log_message: commit message
+        :param datetime.datetime commit_date: the commit date to use (any
+            sub-second part of the timestamp is truncated). If None, use the
+            current date.
+        :param datetime.datetime author_date: overrides the author date
+            normally parsed from the changelog entry (i.e. for handling date
+            parsing edge cases). Any sub-second part of the timestamp is
+            truncated.
+        :returns: reference to the created commit
+        :rtype: pygit2.Oid
+        """
+        if commit_date is None:
+            commit_date = datetime.datetime.now()
+
+        commit_time, commit_offset = datetime_to_signature_spec(commit_date)
+        changelog = self.get_changelog_from_treeish(str(tree))
+
+        return self.raw_repo.create_commit(
+            None,  # ref: do not update any ref
+            pygit2.Signature(*changelog.git_authorship(author_date)),  # author
+            pygit2.Signature(  # committer
+                name=gitubuntu.spec.SYNTHESIZED_COMMITTER_NAME,
+                email=gitubuntu.spec.SYNTHESIZED_COMMITTER_EMAIL,
+                time=commit_time,
+                offset=commit_offset,
+            ),
+            log_message,  # message
+            tree,  # tree
+            parents,  # parents
+        )
+
+
+    @classmethod
+    def _create_replacement_tree_builder(cls, repo, treeish, sub_path):
+        '''Create a replacement TreeBuilder
+
+        Create a TreeBuilder based on an existing repository, top-level
+        tree-ish and path inside that tree.
+
+        A sub_path of '' is taken to mean a request for a replacement
+        TreeBuilder for the top level tree.
+
+        Returns a TreeBuilder object pre-populated with the previous contents.
+        If the path did not previously exist in the tree-ish, then return an
+        empty TreeBuilder instead.
+        '''
+
+        tree = treeish.peel(pygit2.GIT_OBJ_TREE)
+
+        # Short path: sub_path == '' means want root
+        if not sub_path:
+            return repo.TreeBuilder(tree)
+
+        try:
+            tree_entry = tree[sub_path]
+        except KeyError:
+            # sub_path does not exist in tree, so return an empty TreeBuilder
+            tree_builder = repo.TreeBuilder()
+        else:
+            # The tree entry must itself be a tree
+            assert tree_entry.filemode == pygit2.GIT_FILEMODE_TREE
+            sub_tree = repo.get(tree_entry.id).peel(pygit2.GIT_OBJ_TREE)
+            tree_builder = repo.TreeBuilder(sub_tree)
+
+        return tree_builder
+
+    @classmethod
+    def _add_missing_tree_dirs(cls, repo, top_path, top_tree_object, _sub_path=''):
+        """
+        Recursively add empty directories to a tree object
+
+        Find empty directories under top_path and make sure that empty tree
+        objects exist for them. If this means that the tree object must change,
+        then a replacement tree object is created accordingly.
+
+        repo: pygit2.Repository object
+        top_path: path to the extracted contents of the tree
+        top_tree_object: tree object
+        _sub_path (internal): relative path for where we are for recursive call
+
+        Returns None if oid unchanged, or oid if it changed.
+        """
+
+        # full path to our _sub_path, including top_path
+        full_path = os.path.join(top_path, _sub_path)
+
+        dir_list = os.listdir(full_path)
+        if not dir_list:
+            # directory is empty, so this is always the empty tree object
+            return repo.TreeBuilder().write()
+
+        # tree_builder is None if we don't need one yet, or is the replacement
+        # for the tree object for this recursive call
+        tree_builder = None
+        for entry in dir_list:
+            entry_path = os.path.join(full_path, entry)
+            # We cannot use os.path.isdir() here as we don't want to recurse
+            # down symlinks to directories.
+            if stat.S_ISDIR(os.lstat(entry_path).st_mode):
+                # this is a directory, so recurse down
+                entry_oid = cls._add_missing_tree_dirs(
+                    repo=repo,
+                    top_path=top_path,
+                    top_tree_object=top_tree_object,
+                    _sub_path=os.path.join(_sub_path, entry),
+                )
+                if entry_oid:
+                    # The recursive call reported a change to the tree, so we
+                    # must adopt it in what we return to propogate the change
+                    # upwards.
+                    if tree_builder is None:
+                        # There is no replacement in progress for this
+                        # recursive call's tree object, so start one.
+                        tree_builder = cls._create_replacement_tree_builder(
+                            repo=repo,
+                            treeish=top_tree_object,
+                            sub_path=_sub_path,
+                        )
+                    # If the entry previous existed, remove it.
+                    if tree_builder.get(entry):
+                        tree_builder.remove(entry)
+                    # Add the replacement tree entry
+                    tree_builder.insert(           # (takes no kwargs)
+                        entry,                     # name
+                        entry_oid,                 # oid
+                        pygit2.GIT_FILEMODE_TREE,  # attr
+                    )
+
+        if tree_builder is None:
+            return None  # no changes
+        else:
+            return tree_builder.write()  # create replacement tree object
+
+    @classmethod
+    def dir_to_tree(cls, pygit2_repo, path, escape=False):
+        """Create a git tree object from the given filesystem path
+
+        :param pygit2.Repository pygit2_repo: the repository on which to
+            operate. If you have a GitUbuntuRepository instance, you can use
+            its raw_repo property.
+        :param path: path to filesystem directory to be the root of the tree
+        :param escape: if True, escape using escape_dot_git() first. This
+                       mutates the provided filesystem tree.
+
+        escape should be used when the directory being moved into git is
+        directly from a source package, since the source package may contain
+        files or directories named '.git' and these cannot otherwise be
+        represented in a git tree object.
+
+        escape should not be used if the directory has already been escaped
+        previously. For example: if escape was previously used to move into a
+        git tree object, and that git tree object has been extracted to a
+        working directory for manipulation without unescaping, then escape
+        should not be used again to move that result back into a git tree
+        object.
+        """
+        if escape:
+            escape_dot_git(path)
+        # git expects the index file to not exist (in order to create a fresh
+        # one), so create a temporary directory to put it in so we have a name
+        # we can use safely.
+        with tempfile.TemporaryDirectory() as index_dir:
+            index_path = os.path.join(index_dir, 'index')
+            def indexed_git_run(*args):
+                return git_run(
+                    pygit2_repo=pygit2_repo,
+                    args=args,
+                    work_tree_path=path,
+                    index_path=index_path,
+                )
+            indexed_git_run('add', '-f', '-A')
+            indexed_git_run('reset', 'HEAD', '--', '.git')
+            indexed_git_run('reset', 'HEAD', '--', '.pc')
+            tree_hash_str, _ = indexed_git_run('write-tree')
+            tree_hash_str = tree_hash_str.strip()
+            tree = pygit2_repo.get(tree_hash_str)
+
+            # Add any empty directories that git did not import. Workaround for LP:
+            # #1687057.
+            replacement_oid = cls._add_missing_tree_dirs(
+                repo=pygit2_repo,
+                top_path=path,
+                top_tree_object=tree,
+            )
+            if replacement_oid:
+                # Empty directories had to be added
+                return str(replacement_oid)  # return the replacement instead
+            else:
+                # No empty directories were added
+                return tree_hash_str         # no replacement was needed
+
+    @contextmanager
+    def temporary_worktree(self, commitish, prefix=None):
+        with tempfile.TemporaryDirectory(prefix=prefix) as tempdir:
+            self.git_run(
+                [
+                    'worktree',
+                    'add',
+                    '--detach',
+                    '--force',
+                    tempdir,
+                    commitish,
+                ]
+            )
+
+            oldcwd = os.getcwd()
+            os.chdir(tempdir)
+
+            try:
+                yield
+            except:
+                raise
+            finally:
+                os.chdir(oldcwd)
+
+        self.git_run(['worktree', 'prune'])
+
+    def tree_hash_after_command(self, commitish, cmd):
+        with self.temporary_worktree(commitish):
+            try:
+                run(cmd)
+            except CalledProcessError as e:
+                logging.error("Unable to execute `%s`", ' '.join(cmd))
+                raise
+
+            run(["git", "add", "-f", ".",])
+            tree_hash, _ = run(["git", "write-tree"])
+            return tree_hash.strip()
+
+    def tree_hash_subpath(self, treeish_string, path):
+        """Get the tree hash for path at a given treeish
+
+        Arguments:
+        @treeish_string: a string Git treeish
+        @path: a string path present in @treeish_string
+
+        Returns:
+        String hash of Git tree corresponding to @path in @treeish_string
+        """
+        tree_obj = self.raw_repo.revparse_single(treeish_string).peel(
+            pygit2.Tree
+        )
+        return str(tree_obj[path].id)
+
+    def paths_are_identical(self, treeish1_string, treeish2_string, path):
+        """Determine if a given path is the same in two treeishs
+
+        Arguments:
+        @treeish1_string: a string Git treeish
+        @treeish2_string: a string Git treeish
+        @path: a string path present in @treeish1_string and @treeish2_string
+
+        Returns:
+        True, if @path is the same in @treeish1_string and @treeish2_string
+        False, otherwise
+        """
+        try:
+            subpath_tree_hash1 = self.tree_hash_subpath(
+                treeish1_string,
+                path,
+            )
+        except KeyError:
+            # if the path does not exist in treeish
+            subpath_tree_hash1 = None
+        try:
+            subpath_tree_hash2 = self.tree_hash_subpath(
+                treeish2_string,
+                path,
+            )
+        except KeyError:
+            subpath_tree_hash2 = None
+
+        return subpath_tree_hash1 == subpath_tree_hash2
+
+    @lru_cache()
+    def quilt_env(self, treeish):
+        """Return a suitable environment for running quilt.
+
+        This varies depending on the supplied commit since both
+        debian/patches/series and debian/patches/debian.series may be valid.
+        See dpkg-source(1) for details.
+
+        The returned environment includes all necessary variables by
+        combining self.env with the needed quilt-specific environment.
+
+        :param pygit.Object treeish: object that peels to the pygit2.Tree on
+            which quilt will operate.
+        :rtype: dict
+        :returns: an environment suitable for running quilt.
+        """
+        env = self.env.copy()
+        env.update(quilt_env(self.raw_repo, treeish))
+        return env
+
+    def quilt_env_from_treeish_str(self, treeish_str):
+        """Return a suitable environment for running quilt.
+
+        This is a thin wrapper around quilt_env() that works with a treeish hex
+        string instead of directly with a treeish object.
+
+        :param str treeish_str: the hash of the tree on which quilt will
+            operate, in hex.
+        :rtype: dict
+        :returns: an environment suitable for running quilt.
+        """
+        return self.quilt_env(self.raw_repo.get(treeish_str))
+
+    def is_patches_applied(self, commit_hash, regenerated_pc_path):
+        # first see if quilt push -a would do anything to
+        # differentiate between applied and unapplied
+        with self.temporary_worktree(commit_hash):
+            try:
+                run_quilt(
+                    ['push', '-a'],
+                    env=self.quilt_env_from_treeish_str(commit_hash),
+                )
+                # False if in an unapplied state, which is signified by
+                # successful push (rc=0)
+                return False
+            except CalledProcessError as e:
+                # non-zero return might be an error or it might mean no
+                # patches exist
+                if e.returncode == 1:
+                    # an error may occur if we need to recreate the .pc
+                    # first
+                    try:
+                        # the first quilt push may have created a .pc/
+                        shutil.rmtree('.pc')
+                        shutil.copytree(
+                            regenerated_pc_path,
+                            '.pc',
+                        )
+                    except FileNotFoundError:
+                        # if there was no .pc directory, then the first
+                        # quilt push failure was a real error
+                        raise e
+
+                    try:
+                        run_quilt(
+                            ['push', '-a'],
+                            env=self.quilt_env_from_treeish_str(commit_hash),
+                        )
+                        # False if in an unapplied state
+                        return False
+                    except CalledProcessError as e:
+                        # True if in a patches-applied state or
+                        # there are no patches to apply
+                        if e.returncode == 2:
+                            return True
+                        else:
+                            raise
+                # True if in a patches-applied state or there are
+                # no patches to apply
+                elif e.returncode == 2:
+                    return True
+                else:
+                    raise
+
+    def _maybe_quiltify_tree_hash(self, commit_hash):
+        """Determine if quiltify is needed and yield the quiltify'd tree hash
+
+        The imported patches-applied trees do not contain .pc
+        directories. To determine if an additional quilt patch is
+        necessary, we have to first regenerate the .pc directory, then
+        see if dpkg-source --commit generates a new quilt patch.
+
+        In order for dpkg-source --commit to function, we need to know
+        if the commit we are building is patches-unapplied or
+        patches-applied. In the latter case, we can build the commit
+        directly after copying the regenerated .pc directory. In the
+        former case, we do not want to copy the regenerated .pc
+        directory, as dpkg-source will do this for us, as it applies the
+        current patches. We determine if patches are applied or
+        unapplied by relying on `quilt push -a`'s exit status at
+        @commit_hash.
+
+        This is a common method used by multiple callers.
+
+        Arguments:
+        @commit_hash: a string Git commit hash
+
+        Returns:
+        String tree hash of quiltify'ing @commit_hash.
+        If no quiltify is needed, the return value is @commit_hash's
+        tree hash
+        """
+        commit_tree_hash = str(
+            self.raw_repo.get(commit_hash).peel(pygit2.Tree).id
+        )
+        if not is_3_0_quilt(self, commit_hash):
+            return commit_tree_hash
+        # the tarballs need to be in the parent directory from where
+        # we need the orig tarballs for quilt and dpkg-source
+        # but suppress any logging
+        logger = logging.getLogger()
+        oldLevel = logger.getEffectiveLevel()
+        logger.setLevel(logging.WARNING)
+        tarballs = gitubuntu.build.fetch_orig(
+            orig_search_list=gitubuntu.build.derive_orig_search_list_from_args(
+                self,
+                commitish=commit_hash,
+                for_merge=False,
+                no_pristine_tar=False,
+            ),
+            changelog=Changelog.from_treeish(
+                self.raw_repo,
+                self.raw_repo.get(commit_hash)
+            ),
+        )
+        logger.setLevel(oldLevel)
+        # run dpkg-source
+        with tempfile.TemporaryDirectory() as tempdir:
+            # copy the generated tarballs
+            new_tarballs = []
+            for tarball in tarballs:
+                new_tarballs.append(shutil.copy(tarball, tempdir))
+            tarballs = new_tarballs
+
+            # create a nested temporary directory where we will recreate
+            # the .pc directory
+            with tempfile.TemporaryDirectory(prefix=tempdir+'/') as ttempdir:
+                oldcwd = os.getcwd()
+                os.chdir(ttempdir)
+
+                for tarball in tarballs:
+                    run(['tar', '-x', '--strip-components=1', '-f', tarball,])
+
+                # need the debia/patches
+                shutil.copytree(
+                    os.path.join(self.local_dir, 'debian',),
+                    'debian',
+                )
+
+                # generate the equivalent .pc directory
+                run_quilt(
+                    ['push', '-a'],
+                    env=self.quilt_env_from_treeish_str(commit_hash),
+                    rcs=[2],
+                )
+
+                regenerated_pc_path = os.path.join(tempdir, '.pc')
+
+                if os.path.exists(".pc"):
+                    shutil.copytree(
+                        '.pc',
+                        regenerated_pc_path,
+                    )
+
+                os.chdir(oldcwd)
+
+            patches_applied = self.is_patches_applied(
+                commit_hash,
+                regenerated_pc_path,
+            )
+
+            with self.temporary_worktree(commit_hash, prefix=tempdir+'/'):
+                # we only need to copy the generated .pc directory
+                # if we are building a patches-applied tree, which
+                # we determine by comparing our current tree hash to
+                # the generated tree hash.
+                if patches_applied:
+                    try:
+                        shutil.copytree(
+                            regenerated_pc_path,
+                            '.pc',
+                        )
+                    except FileNotFoundError:
+                        # it is possible no quilt patches exist yet
+                        pass
+
+                fixup_patch_path = os.path.join(
+                    'debian',
+                    'patches',
+                    'git-ubuntu-fixup.patch'
+                )
+
+                if os.path.exists(fixup_patch_path):
+                    raise ValueError(
+                        "A quilt patch with the name git-ubuntu-fixup.patch "
+                        "already exists in %s" % commit_hash
+                    )
+
+                run(
+                    [
+                        'dpkg-source',
+                        '--commit',
+                        '.',
+                        'git-ubuntu-fixup.patch',
+                    ],
+                    env=self.quilt_env_from_treeish_str(commit_hash),
+                )
+
+                # do not want the .pc directory in the resulting
+                # treeish
+                if os.path.exists('.pc'):
+                    shutil.rmtree('.pc')
+
+                if os.path.exists(fixup_patch_path):
+                    # dpkg-source uses debian/changelog to generate some
+                    # fields. We do not know yet if the changelog has
+                    # been updated, so elide that section of comments.
+                    with open(fixup_patch_path, 'r+') as f:
+                        for line in f:
+                            if '---' in line:
+                                break
+                        text = """Description: git-ubuntu generated quilt fixup patch
+TODO: Put a short summary on the line above and replace this paragraph
+with a longer explanation of this change. Complete the meta-information
+with other relevant fields (see below for details).
+---\n"""
+                        for line in f:
+                            text += line
+                        f.seek(0)
+                        f.write(text)
+                        f.truncate()
+
+                    # If we are on a patches-unapplied tree, then we
+                    # need to reset ourselves back to @commit_hash with
+                    # our new patch.
+                    # In order for this to be buildable, we have to
+                    # reverse-apply our patch, to undo the git-commited
+                    # upstream changes.
+                    if not patches_applied:
+                        run(['git', 'add', '-f', 'debian/patches',])
+                        # if any patches add files that are untracked,
+                        # remove them
+                        run(['git', 'clean', '-f', '-d',])
+                        # reset all the other files to their status in
+                        # HEAD
+                        run(['git', 'checkout', commit_hash, '--', '*',])
+                        with open(fixup_patch_path, 'rb') as f:
+                            run(['patch', '-Rp1',], input=f.read())
+
+                    return self.dir_to_tree(self.raw_repo, '.')
+                else:
+                    return commit_tree_hash
+
+    def maybe_quiltify_tree_hash(self, commitish_string):
+        """Determine if quiltify is needed and return the quiltify'd tree hash
+
+        See _maybe_quiltify_tree_hash for details.
+
+        Arguments:
+        @commitish_string: a string Git commitish
+
+        Returns:
+        String tree hash of quiltify'ing @commitish_string.
+        If no quiltify is needed, the return value is the tree hash of
+        @commitish_string.
+        """
+        commit_hash = str(
+            self.get_commitish(commitish_string).peel(pygit2.Commit).id
+        )
+        return self._maybe_quiltify_tree_hash(commit_hash)
+
+    def maybe_changelogify_tree_hash(self, commit_hash):
+        """Determine if changelogify is needed and yield the changelogify'd tree hash
+
+        Given a commit, we need to detect if the user has inserted a
+        changelog entry relative to a published version for the purpose
+        of test builds.
+
+        Arguments:
+        @commit_hash: a string Git commit hash
+
+        Returns:
+        String tree hash of changelogify'ing @commit_hash.
+        If no changelogify is needed, the return value is the tree hash of
+        @commit_hash.
+        """
+        commit_tree_hash = str(
+            self.raw_repo.get(commit_hash).peel(pygit2.Tree).id
+        )
+
+        # one of these are the "base" pkg that @commit_hash's changes
+        # are based on
+        remote_tag = self.nearest_tag(
+            commit_hash,
+            prefix='pkg/',
+        )
+        remote_branch = derive_target_branch(
+            self,
+            commit_hash,
+        )
+
+        assert remote_tag or remote_branch
+
+        if remote_tag:
+            if remote_branch:
+                try:
+                    self.git_run(
+                        [
+                            'merge-base',
+                            '--is-ancestor',
+                            remote_tag.name,
+                            remote_branch,
+                        ],
+                        verbose_on_failure=False,
+                    )
+                    parent_ref = remote_branch
+                except CalledProcessError as e:
+                    if e.returncode == 1:
+                        parent_ref = remote_tag.name
+                    else:
+                        raise
+            else:
+                parent_ref = remote_tag.name
+        else:
+            parent_ref = remote_branch
+
+        # If there are any changes relative to parent_ref but there are
+        # not any changelog changes, insert a snapshot changelog entry,
+        # starting from parent_ref, and return the resulting tree hash.
+        if str(self.raw_repo.revparse_single(parent_ref).peel(
+            pygit2.Tree
+        ).id) != commit_tree_hash and self.paths_are_identical(
+            parent_ref,
+            commit_hash,
+            'debian/changelog',
+        ):
+            with self.temporary_worktree(commit_hash):
+                run_gbp(
+                    [
+                        'dch',
+                        '--snapshot',
+                        '--ignore-branch',
+                        '--since=%s' % str(parent_ref),
+                    ],
+                    env=self.env,
+                )
+                return self.dir_to_tree(self.raw_repo, '.')
+
+        # otherwise, return @commit_hash's tree hash
+        return commit_tree_hash
+
+    def quiltify_and_changelogify_tree_hash(self, commitish_string):
+        """Given a commitish, possibly quiltify and changelogify its tree
+
+        Definitions:
+            quiltify: generate a quilt patch from untracked upstream
+            changes
+            changelogify: generate a snapshot changelog entry if any
+            changes exist, and no new changelog entry yet exists
+
+        Arguments:
+        @commitish_string: string Git commitish
+
+        Returns:
+        string Git tree hash of quiltify-ing and changelogify-ing
+        @commitish_string, if needed
+        if neither quiltify or changelogify are needed, return
+        @commitish_string's tree hash
+        """
+        commit_hash = str(
+            self.get_commitish(commitish_string).peel(pygit2.Commit).id
+        )
+        quiltify_tree_hash = self._maybe_quiltify_tree_hash(commit_hash)
+        changelogify_tree_hash = self.maybe_changelogify_tree_hash(commit_hash)
+
+        quiltify_tree_obj = self.raw_repo.get(quiltify_tree_hash)
+        changelogify_tree_obj = self.raw_repo.get(changelogify_tree_hash)
+
+        # There are multiple ways to solve this problem, but the
+        # simplest is to use a TreeBuilder to merge the quiltify tree
+        # with the changelog from the changelogify tree
+        # top-level TreeBuilder
+        tb = self.raw_repo.TreeBuilder(quiltify_tree_obj)
+        te = tb.get('debian')
+        # TreeBuilder for debian/
+        dtb = self.raw_repo.TreeBuilder(self.raw_repo.get(te.id))
+        dtb.insert( # does not take kwargs
+            'changelog',                                   # name
+            changelogify_tree_obj['debian/changelog'].oid, # oid
+            pygit2.GIT_FILEMODE_BLOB,                      # attr
+        )
+        # insert can replace
+        tb.insert( # does not take kwargs
+            'debian',                 # name
+            dtb.write(),              # oid
+            pygit2.GIT_FILEMODE_TREE, # attr
+        )
+        return str(tb.write())
+
+    def find_ubuntu_merge_base(
+        self,
+        ubuntu_commitish,
+    ):
+        """Find the Ubuntu merge point for a given Ubuntu version
+
+        :param ubuntu_commitish str A commitish describing the latest
+            Ubuntu commit
+
+        :rtype str
+        :returns Commit hash of import of Debian version
+            @ubuntu_commitish is based on. The imported Debian version
+            must be an ancestor of @ubuntu_commitish. If no suitable
+            commit is found, an empty string is returned.
+        """
+        merge_base_tag = None
+
+        # obtain the nearest imported Debian version per the changelog
+        for version in self.get_all_changelog_versions_from_treeish(
+            ubuntu_commitish,
+        ):
+            # extract corresponding Debian version
+            debian_parts, _ = gitubuntu.versioning.split_version_string(
+                version
+            )
+            expected_debian_version = "".join(debian_parts)
+
+            # We do not currently handle the case of a Debian version
+            # being reimported. I think the proper way to support that
+            # would be to add a parameter to `git ubuntu merge` for the
+            # user to tell us which reimport tag is the one the Ubuntu
+            # delta is based on.
+            merge_base_tag = self.get_import_tag(
+                expected_debian_version,
+                'pkg',
+            )
+
+            if merge_base_tag:
+                assert not self.get_all_reimport_tags(
+                    expected_debian_version,
+                    'pkg',
+                )
+                break
+
+        if not merge_base_tag:
+            logging.error(
+                "Unable to find an import tag for any Debian version "
+                "in %s:debian/changelog.",
+                ubuntu_commitish,
+            )
+            return ''
+
+        merge_base_commit_hash = str(merge_base_tag.peel(pygit2.Commit).id)
+
+        try:
+            self.git_run(
+                [
+                    'merge-base',
+                    '--is-ancestor',
+                    merge_base_commit_hash,
+                    ubuntu_commitish,
+                ],
+                verbose_on_failure=False,
+            )
+        except CalledProcessError as e:
+            if e.returncode != 1:
+                raise
+            logging.error(
+                "Found an import tag for %s (commit: %s), but it is "
+                "not an ancestor of %s.",
+                expected_debian_version,
+                merge_base_commit_hash,
+                ubuntu_commitish,
+            )
+            return ''
+
+        return merge_base_commit_hash
+>>>>>>> gitubuntu/git_repository.py
diff --git a/gitubuntu/git_repository_test.py b/gitubuntu/git_repository_test.py
new file mode 100644
index 0000000..72055f9
--- /dev/null
+++ b/gitubuntu/git_repository_test.py
@@ -0,0 +1,1191 @@
+<<<<<<< gitubuntu/git_repository_test.py
+=======
+import copy
+import datetime
+import itertools
+import os
+import pkg_resources
+import shutil
+import tempfile
+import unittest
+import unittest.mock
+
+import pygit2
+import pytest
+
+import gitubuntu.git_repository as target
+from gitubuntu.git_repository import HeadInfoItem
+from gitubuntu.repo_builder import (
+    Blob,
+    Commit,
+    Placeholder,
+    Repo,
+    SourceTree,
+    Symlink,
+    Tree,
+)
+from gitubuntu.source_builder import Source, SourceSpec
+import gitubuntu.spec
+from gitubuntu.test_fixtures import (
+    repo,
+    pygit2_repo,
+)
+from gitubuntu.test_util import get_test_changelog
+
+
[e-mail]('same_remote_branch_names, different_remote_branch_names, expected', [
+    ([], [], ''),
+    (['pkg/ubuntu/xenial-devel',], [], 'pkg/ubuntu/xenial-devel'),
+    (['pkg/ubuntu/xenial-security',], [], 'pkg/ubuntu/xenial-security'),
+    (['pkg/ubuntu/xenial-updates', 'pkg/ubuntu/xenial-devel'], [],
+        'pkg/ubuntu/xenial-devel'
+    ),
+    ([], ['pkg/ubuntu/xenial-updates', 'pkg/ubuntu/xenial-devel'],
+        ''
+    ),
+    (['pkg/ubuntu/zesty-devel', 'pkg/ubuntu/zesty-proposed', 'pkg/ubuntu/devel'], [], 'pkg/ubuntu/devel'),
+])
+def test__derive_target_branch_string(same_remote_branch_names,
+    different_remote_branch_names, expected
+):
+    remote_branch_objects = []
+    for branch_name in same_remote_branch_names:
+        b = unittest.mock.Mock()
+        b.peel(pygit2.Tree).id = unittest.mock.sentinel.same_id
+        b.branch_name = branch_name
+        remote_branch_objects.append(b)
+    for branch_name in different_remote_branch_names:
+        b = unittest.mock.Mock()
+        b.peel(pygit2.Tree).id = object() # need a different sentinel for each
+        b.branch_name = branch_name
+        remote_branch_objects.append(b)
+    target_branch_string = target._derive_target_branch_string(
+        remote_branch_objects
+    )
+    assert target_branch_string == expected
+
+
[e-mail]('changelog_name, expected', [
+    ('test_versions_1', ['1.0', None]),
+    ('test_versions_2', ['2.0', '1.0']),
+    ('test_versions_3', ['4.0', '3.0']),
+    ('test_versions_unknown', ['ss-970814-1', None]),
+])
+def test_changelog_versions(changelog_name, expected):
+    test_changelog = get_test_changelog(changelog_name)
+    assert [test_changelog.version, test_changelog.previous_version] == expected
+
+
[e-mail]('changelog_name, expected', [
+    ('test_versions_unknown', ['ss-970814-1',]),
+])
+def test_changelog_all_versions(changelog_name, expected):
+    test_changelog = get_test_changelog(changelog_name)
+    assert test_changelog.all_versions == expected
+
+
+def test_changelog_distribution():
+    test_changelog = get_test_changelog('test_distribution')
+    assert test_changelog.distribution == 'xenial'
+
+
+def test_changelog_date():
+    test_changelog = get_test_changelog('test_date_1')
+    assert test_changelog.date == 'Mon, 12 May 2016 08:14:34 -0700'
+    test_changelog = get_test_changelog('test_date_2')
+    assert test_changelog.date == 'Mon, 12 May 2016 08:14:34 -0700'
+
+
[e-mail]('changelog_name, expected', [
+    ('test_maintainer_1', 'Test Maintainer <[e-mail]>'),
+    ('test_maintainer_2', '<[e-mail]>'),
+])
+def test_changelog_maintainer(changelog_name, expected):
+    test_changelog = get_test_changelog(changelog_name)
+    assert test_changelog.maintainer == expected
+
+
+def test_changelog_maintainer_invalid():
+    with pytest.raises(ValueError):
+        test_changelog = get_test_changelog('test_maintainer_3')
+        test_changelog.maintainer
+
+
+def test_changelog_multiple_angle_brackets():
+    """An email address with extra angle brackets should still parse"""
+    test_changelog = get_test_changelog('test_multiple_angle_brackets')
+    assert test_changelog.git_authorship()[1] == '[e-mail]'
+
+
[e-mail](['input_date_string', 'expected_result'], [
+    # The normal complete form
+    ('Mon, 12 May 2016 08:14:34 -0700', (2016, 5, 12, 8, 14, 34, -7)),
+    # Day of week missing, such as in:
+    #     datefudge 1.12
+    ('12 May 2016 08:14:34 -0700', (2016, 5, 12, 8, 14, 34, -7)),
+    # Full (not abbreviated) month name, such as in:
+    #     dnsmasq 2.32-2
+    #     dropbear 0.42-1
+    #     e2fsprogs 1.42.11-1
+    #     efibootmgr 0.5.4-7
+    #     hunspell-br 0.11-1
+    #     kubuntu-default-settings 1:6.06-22
+    #     libvformat 1.13-4
+    ('12 June 2016 08:14:34 -0700', (2016, 6, 12, 8, 14, 34, -7)),
+    # Full (not abbreviated) day of week name, such as in:
+    #     logcheck 1.2.22a
+    ('Thursday, 15 May 2016 08:14:34 -0700', (2016, 5, 15, 8, 14, 34, -7)),
+    # Part-abbreviated day of week name, such as in:
+    #     kubuntu-meta 1.76
+    ('Thur, 15 May 2016 08:14:34 -0700', (2016, 5, 15, 8, 14, 34, -7)),
+])
+def test_parse_changelog_date(input_date_string, expected_result):
+    """_parse_changelog_date should parse a basic date string correctly
+
+    :param str input_date_string: the timestamp part of the changelog signoff
+        line
+    :param tuple(int, int, int, int, int, int, int) expected_result: the
+        expected parse result in (year, month, day, hour, minute, second,
+        timezone_offset_in_hours) form. The actual expected result needs to be
+        a datetime.datetime object; to avoid duplication in test parameters
+        this will be instantiated within the test.
+    """
+    actual_result = target.Changelog._parse_changelog_date(input_date_string)
+    expected_result_datetime = datetime.datetime(
+        *expected_result[:6],
+        tzinfo=datetime.timezone(datetime.timedelta(hours=expected_result[6])),
+    )
+    assert actual_result == expected_result_datetime
+
+
[e-mail](['input_date_string'], [
+    ('Mon, 30 Feb 2020 15:50:58 +0200',),  # ghostscript 9.50~dfsg-5ubuntu4
+    ('Mon, 03 Sep 2018 00:43:25 -7000',),  # lxqt-config 0.13.0-0ubuntu4
+    ('Tue, 17 May 2008 10:93:55 -0500',),  # iscsitarget
+                                           #     0.4.15+svn148-2.1ubuntu1
+    ('Monu, 22 Jan 2007 22:10:50 -0500',), # mail-spf-perl 2.004-0ubuntu1
+    ('Wed, 29 Augl 2007 16:14:11 +0200',), # nut 2.2.0-2
+])
+def test_changelog_date_parse_errors(input_date_string):
+    """_parse_changelog_date should raise ValueError on illegal dates
+
+    :param str input_date_string: the timestamp part of the changelog signoff
+        line
+    """
+    with pytest.raises(ValueError):
+        target.Changelog._parse_changelog_date(input_date_string)
+
+
[e-mail](
+    'changelog_name, name, email, epoch_seconds, offset', [
+        (
+            'test_maintainer_1',
+            'Test Maintainer',
+            '[e-mail]',
+            0,
+            0,
+        ),
+        (
+            'test_maintainer_2',
+            'Unnamed',  # git won't handle empty names; see the spec
+            '[e-mail]',
+            0,
+            0,
+        ),
+        (
+            'test_date_1',
+            'Test Maintainer',
+            '[e-mail]',
+            1463066074,
+            -420,
+        ),
+        (
+            'test_date_2',
+            'Test Maintainer',
+            '[e-mail]',
+            1463066074,
+            -420,
+        ),
+        (
+            'maintainer_name_leading_space',
+            'Test Maintainer',
+            '[e-mail]',
+            0,
+            0,
+        ),
+        (
+            'maintainer_name_trailing_space',
+            'Test Maintainer',
+            '[e-mail]',
+            0,
+            0,
+        ),
+        (
+            'maintainer_name_inner_space',
+            'Test  Maintainer',
+            '[e-mail]',
+            0,
+            0,
+        ),
+])
+def test_changelog_authorship(
+    changelog_name,
+    name,
+    email,
+    epoch_seconds,
+    offset,
+):
+    result = get_test_changelog(changelog_name).git_authorship()
+    assert result == (name, email, epoch_seconds, offset)
+
+
+def test_changelog_utf8():
+    test_changelog = get_test_changelog('test_utf8_error')
+    assert test_changelog.version == '1.0.3-2'
+
+
+def test_changelog_duplicate():
+    # Changelog.all_versions should successfully return without an assertion
+
+    # Xenial's dpkg-parsechangelog eliminates duplicate versions. Bionic's
+    # dpkg-parsechangelog does not. We rely on the behaviour of
+    # dpkg-parsechangelog from Bionic, where this test passes. The test fails
+    # when using Xenial's dpkg-parsechangelog, where its behaviour doesn't
+    # match our assumptions elsewhere.
+
+    # -with-extra includes an extra changelog entry at the end. This is
+    # currently needed to trip the assertion because it truncates the longer
+    # list before its comparison. This will get fixed in a subsequent commit,
+    # but using it here ensures that this test will correctly trip regardless
+    # of the presence of that unrelated bug.
+    test_changelog = get_test_changelog('duplicate-version-with-extra')
+    test_changelog.all_versions
+
+
+def test_changelog_all_versions_assertion_mismatched_length():
+    # if Changelog.all_versions finds that self._changelog.versions mismatches
+    # self._shell_all_versions, it is supposed to raise an assertion. Here is
+    # an edge case where at one point in development it did not. We fake both
+    # _changelog.versions and _shell_all_versions to an edge case where they
+    # mismatch.
+    with unittest.mock.patch(
+        'gitubuntu.git_repository.Changelog._shell_all_versions',
+        new_callable=unittest.mock.PropertyMock
+    ) as mock_shell_all_versions:
+        mock_shell_all_versions.return_value = ['a']
+        test_changelog = target.Changelog(b'')
+        test_changelog._changelog = unittest.mock.Mock()
+        test_changelog._changelog.versions = ['a', 'b']
+        with pytest.raises(target.ChangelogError):
+            test_changelog.all_versions
+
+
[e-mail]('tree_func', [
+    # The tree_func parameter is a function that accepts a mock Blob that is to
+    # represent the changelog blob itself and returns a mock Tree with the mock
+    # Blob embedded somewhere within it. The test function can then ensure that
+    # follow_symlinks_to_blob can correctly find the changelog Blob given the
+    # Tree.
+
+    # Of course this is only expected to work if, after checking out the Tree,
+    # "cat debian/changelog" would work. But this allows us to test the various
+    # permutations of symlink following in Trees that _are_ valid.
+
+    # Simple case
+    lambda b: Tree({
+        'debian': Tree({'changelog': b}),
+    }),
+
+    # Symlink in debian/
+    lambda b: Tree({
+        'debian': Tree({
+                    'changelog.real': b,
+                    'changelog': Symlink('changelog.real'),
+                }),
+    }),
+
+    # Symlink to parent directory
+    lambda b: Tree({
+        'changelog': b,
+        'debian': Tree({
+            'changelog': Symlink('../changelog'),
+        })
+    }),
+
+    # Symlink to subdirectory
+    lambda b: Tree({
+        'debian': Tree({
+            'changelog': Symlink('subdirectory/changelog'),
+            'subdirectory': Tree({'changelog': b}),
+        })
+    }),
+
+    # debian/ itself is a symlink to a different directory
+    lambda b: Tree({
+        'pkg': Tree({'changelog': b}),
+        'debian': Symlink('pkg'),
+    })
+])
+def test_follow_symlinks_to_blob(pygit2_repo, tree_func):
+    blob = Blob(b'')
+    blob_id = blob.write(pygit2_repo)
+    tree = pygit2_repo.get(tree_func(blob).write(pygit2_repo))
+    result_blob = target.follow_symlinks_to_blob(
+        pygit2_repo,
+        tree,
+        'debian/changelog',
+    )
+    assert result_blob.id == blob_id
+
+
[e-mail]('tree', [
+    Tree({}),
+    Tree({'debian': Tree({})}),
+    Tree({'debian': Tree({'changelog': Symlink('other')})}),
+    Tree({'debian': Tree({'changelog': Symlink('../other')})}),
+])
+def test_follow_symlinks_to_blob_not_found(pygit2_repo, tree):
+    pygit2_tree = pygit2_repo.get(tree.write(pygit2_repo))
+    with pytest.raises(KeyError):
+        target.follow_symlinks_to_blob(
+            pygit2_repo,
+            pygit2_tree,
+            'debian/changelog',
+        )
+
+
+def test_renameable_dir_basename(tmpdir):
+    p = tmpdir.join('foo')
+    p.ensure()
+    rd = target.RenameableDir(str(p))
+    assert rd.basename == 'foo'
+
+
+def test_renameable_dir_basename_setter(tmpdir):
+    p = tmpdir.join('foo')
+    p.ensure()
+    rd = target.RenameableDir(str(p))
+    rd.basename = 'bar'
+    assert rd.basename == 'bar'
+    assert tmpdir.join('bar').check()
+
+
+def test_dot_git_match(tmpdir):
+    for name in ['.git', 'git', '..git', 'other']:
+        tmpdir.join(name).ensure()
+
+    result = set(
+        x.basename
+        for x in tmpdir.listdir(
+            fil=lambda x: target._dot_git_match(str(x.basename))
+        )
+    )
+    assert result == set(['.git', '..git'])
+
+
+def test_renameable_dir_listdir(tmpdir):
+    for name in ['.git', 'git', '..git', 'other']:
+        tmpdir.join(name).ensure()
+    rd = target.RenameableDir(str(tmpdir))
+    result = set(rd.listdir(target._dot_git_match))
+    assert result == set([
+        target.RenameableDir(os.path.join(str(tmpdir), '.git')),
+        target.RenameableDir(os.path.join(str(tmpdir), '..git')),
+    ])
+
+
+def test_renamable_dir_recursive(tmpdir):
+    a = tmpdir.join('foo')
+    a.ensure_dir()
+    b = tmpdir.join('bar')
+    b.ensure()
+    assert target.RenameableDir(str(a)).recursive
+    assert not target.RenameableDir(str(b)).recursive
+
+
+def test_renameable_dir_recursive_symlink_directory(tmpdir):
+    """A RenameableDir should not treat a broken symlink as recursive"""
+    test_symlink = tmpdir.join('foo')
+    nonexistent_file = tmpdir.join('nonexistent_file')
+    test_symlink.mksymlinkto(nonexistent_file)
+    assert not target.RenameableDir(str(test_symlink)).recursive
+
+
+def test_renameable_dir_str(tmpdir):
+    p = tmpdir.join('foo')
+    p.ensure()
+    rd = target.RenameableDir(str(p))
+    assert str(rd) == os.path.join(str(tmpdir), 'foo')
+
+
+def test_renameable_dir_repr(tmpdir):
+    p = tmpdir.join('foo')
+    p.ensure()
+    rd = target.RenameableDir(str(p))
+    assert repr(rd) == ("RenameableDir('%s/foo')" % str(tmpdir))
+
+
+def test_renameable_dir_hash_eq(tmpdir):
+    p1a = tmpdir.join('foo')
+    p1b = tmpdir.join('foo')
+    p2 = tmpdir.join('bar')
+
+    p1a.ensure()
+    p2.ensure()
+
+    rd1a = target.RenameableDir(str(p1a))
+    rd1b = target.RenameableDir(str(p1b))
+    rd2 = target.RenameableDir(str(p2))
+
+    assert rd1a == rd1b
+    assert rd1a != rd2
+
+
+def test_renameable_dir_must_exist(tmpdir):
+    """A RenameableDir should reject a path that doesn't exist"""
+    with pytest.raises(FileNotFoundError):
+        target.RenameableDir(tmpdir.join('a'))
+
+
+def test_fake_renameable_dir_basename():
+    path = target.FakeRenameableDir('foo', None)
+    assert path.basename == 'foo'
+
+
+def test_fake_renameable_dir_basename_setter():
+    path = target.FakeRenameableDir('foo', None)
+    path.basename = 'bar'
+    assert path.basename == 'bar'
+
+
+def test_fake_renameable_dir_listdir():
+    path = target.FakeRenameableDir(None, [
+        target.FakeRenameableDir('.git', None),
+        target.FakeRenameableDir('git', None),
+        target.FakeRenameableDir('..git', None),
+        target.FakeRenameableDir('other', None),
+    ])
+    result = set(x.basename for x in path.listdir(fil=target._dot_git_match))
+    assert result == set(['.git', '..git'])
+
+
+def test_fake_renameable_dir_recursive():
+    assert target.FakeRenameableDir(['foo'], []).recursive
+    assert not target.FakeRenameableDir(['foo'], None).recursive
+
+
+def test_fake_renameable_dir_hash_eq():
+    variations = [
+        target.FakeRenameableDir(None, None),
+        target.FakeRenameableDir(None, []),
+        target.FakeRenameableDir('foo', []),
+        target.FakeRenameableDir(None, [
+            target.FakeRenameableDir('foo', None)]
+        ),
+        target.FakeRenameableDir(None, [
+            target.FakeRenameableDir('foo', [
+                target.FakeRenameableDir('bar', None)
+            ]),
+        ]),
+    ]
+    for a, b in itertools.product(variations, variations):
+        if a is b:
+            assert a == b
+        else:
+            assert a != b
+
+
+def test_fake_renameable_dir_repr():
+    rd = target.FakeRenameableDir('foo', [target.FakeRenameableDir('bar', [])])
+    assert (
+        repr(rd) == "FakeRenameableDir('foo', [FakeRenameableDir('bar', [])])"
+    )
+
+
[e-mail]('initial,expected', [
+    # Empty directory remains unchanged
+    (
+        target.FakeRenameableDir(None, []),
+        target.FakeRenameableDir(None, []),
+    ),
+    # Basic .git -> ..git escape
+    (
+        target.FakeRenameableDir(
+            None,
+            [target.FakeRenameableDir('.git', None)],
+        ),
+        target.FakeRenameableDir(
+            None,
+            [target.FakeRenameableDir('..git', None)],
+        ),
+    ),
+    # .git contains a .git
+    (
+        target.FakeRenameableDir(
+            None,
+            [
+                target.FakeRenameableDir(
+                    '.git',
+                    [target.FakeRenameableDir('.git', None)],
+                )
+            ],
+        ),
+        target.FakeRenameableDir(
+            None,
+            [
+                target.FakeRenameableDir(
+                    '..git',
+                    [target.FakeRenameableDir('..git', None)],
+                )
+            ],
+        ),
+    ),
+    # git remains unchanged
+    (
+        target.FakeRenameableDir(
+            None,
+            [target.FakeRenameableDir('git', None)],
+        ),
+        target.FakeRenameableDir(
+            None,
+            [target.FakeRenameableDir('git', None)],
+        ),
+    ),
+    # .git and ..git both exist
+    (
+        target.FakeRenameableDir(
+            None,
+            [
+                target.FakeRenameableDir('.git', None),
+                target.FakeRenameableDir('..git', None),
+            ],
+        ),
+        target.FakeRenameableDir(
+            None,
+            [
+                target.FakeRenameableDir('..git', None),
+                target.FakeRenameableDir('...git', None),
+            ],
+        ),
+    ),
+    # Ordinary directory contains a .git
+    (
+        target.FakeRenameableDir(
+            None,
+            [
+                target.FakeRenameableDir(
+                    'foo',
+                    [target.FakeRenameableDir('.git', None)],
+                )
+            ]
+        ),
+        target.FakeRenameableDir(
+            None,
+            [
+                target.FakeRenameableDir(
+                    'foo',
+                    [target.FakeRenameableDir('..git', None)],
+                )
+            ]
+        ),
+    ),
+])
+def test_escape_dot_git(initial, expected):
+    state = copy.deepcopy(initial)
+    # Once escaped, we should get to what was expected
+    target._escape_unescape_dot_git(state, target._EscapeDirection.ESCAPE)
+    assert state == expected
+    # Once unescaped, we should get back to where we started since the escaping
+    # mechanism is lossless.
+    target._escape_unescape_dot_git(state, target._EscapeDirection.UNESCAPE)
+    assert state == initial
+
+
+def test_unescape_dot_git_raises():
+    """Test that unescaping something with '.git' raises an exception."""
+    with pytest.raises(RuntimeError):
+        target._escape_unescape_dot_git(
+            target.FakeRenameableDir(
+                None,
+                [target.FakeRenameableDir('.git', None)],
+            ),
+            direction=target._EscapeDirection.UNESCAPE,
+        )
+
+
[e-mail]('direction', [
+    target._EscapeDirection.ESCAPE,
+    target._EscapeDirection.UNESCAPE,
+])
+def test_escape_dot_git_ordering(direction):
+    """Test that renames happen in the correct order.
+
+    ...git -> ....git must happen before ..git -> ...git to avoid a collision,
+    and vice versa in the unescape case.
+    """
+    # Avoid '.git' as it isn't valid in the reverse direction
+    inner2 = target.FakeRenameableDir('..git', None)
+    inner3 = target.FakeRenameableDir('...git', None)
+    inputs = [inner2, inner3]
+    if direction is target._EscapeDirection.ESCAPE:
+        expected_order = [inner3, inner2]
+    else:
+        expected_order = [inner2, inner3]
+    for given_order in [inputs, reversed(inputs)]:
+        top = target.FakeRenameableDir(None, given_order)
+        target._escape_unescape_dot_git(top, direction)
+        assert all(x is y for x, y in zip(top._rename_record, expected_order))
+
+
+def test_empty_dir_to_tree(pygit2_repo, tmpdir):
+    tree_hash = target.GitUbuntuRepository.dir_to_tree(
+        pygit2_repo,
+        str(tmpdir),
+    )
+    assert tree_hash == str(Tree({}).write(pygit2_repo))
+
+
+def test_onefile_dir_to_tree(pygit2_repo, tmpdir):
+    tmpdir.join('foo').write('bar')
+    tree_hash = target.GitUbuntuRepository.dir_to_tree(
+        pygit2_repo,
+        str(tmpdir),
+    )
+    assert tree_hash == str(Tree({'foo': Blob(b'bar')}).write(pygit2_repo))
+
+
+def test_git_escape_dir_to_tree(pygit2_repo, tmpdir):
+    tmpdir.mkdir('.git')
+    tree_hash = target.GitUbuntuRepository.dir_to_tree(
+        pygit2_repo,
+        str(tmpdir),
+        escape=True,
+    )
+    assert tree_hash == str(Tree({'..git': Tree({})}).write(pygit2_repo))
+
+
[e-mail]('tree_data,expected_path', [
+    # Empty tree -> default
+    (Tree({}), 'debian/patches/series'),
+
+    # Empty debian/patches directory -> default
+    (Tree({'debian': Tree({'patches': Tree({})})}), 'debian/patches/series'),
+
+    # Only debian/patches/series -> that one
+    (
+        Tree({'debian': Tree({'patches': Tree({'series': Blob(b'')})})}),
+        'debian/patches/series',
+    ),
+
+    # Only debian/patches/debian.series -> that one
+    (
+        Tree({'debian': Tree({'patches': Tree({
+            'debian.series': Blob(b'')
+        })})}),
+        'debian/patches/debian.series',
+    ),
+
+    # Both -> debian.series
+    (
+        Tree({'debian': Tree({'patches': Tree({
+            'debian.series': Blob(b''),
+            'series': Blob(b''),
+        })})}),
+        'debian/patches/debian.series',
+    ),
+])
+def test_determine_quilt_series_path(pygit2_repo, tree_data, expected_path):
+    tree_obj = pygit2_repo.get(tree_data.write(pygit2_repo))
+    path = target.determine_quilt_series_path(pygit2_repo, tree_obj)
+    assert path == expected_path
+
+
+def test_quilt_env(pygit2_repo):
+    tree_builder = Tree({'debian':
+        Tree({'patches': Tree({'debian.series': Blob(b'')})})
+    })
+    tree_obj = pygit2_repo.get(tree_builder.write(pygit2_repo))
+    env = target.quilt_env(pygit2_repo, tree_obj)
+    assert env == {
+        'EDITOR': 'true',
+        'QUILT_NO_DIFF_INDEX': '1',
+        'QUILT_NO_DIFF_TIMESTAMPS': '1',
+        'QUILT_PATCHES': 'debian/patches',
+        'QUILT_SERIES': 'debian/patches/debian.series',
+    }
+
+
+def test_repo_quilt_env(repo):
+    tree_builder = Tree({'debian':
+        Tree({'patches': Tree({'debian.series': Blob(b'')})})
+    })
+    tree_obj = repo.raw_repo.get(tree_builder.write(repo.raw_repo))
+    env = repo.quilt_env(tree_obj)
+    expected_inside = {
+        'EDITOR': 'true',
+        'QUILT_NO_DIFF_INDEX': '1',
+        'QUILT_NO_DIFF_TIMESTAMPS': '1',
+        'QUILT_PATCHES': 'debian/patches',
+        'QUILT_SERIES': 'debian/patches/debian.series',
+    }
+    for k, v in expected_inside.items():
+        assert env[k] == v
+
+    # In addition to the settings above, check that
+    # GitUbuntuRepository.quilt_env has correctly merged in the usual
+    # environment. Testing that a few keys that we expect to be set are set
+    # should suffice.
+    expected_other_keys = ['HOME', 'GIT_DIR', 'GIT_WORK_TREE']
+    for k in expected_other_keys:
+        assert env[k]
+
+
+def test_repo_quilt_env_from_treeish_str(repo):
+    tree_builder = Tree({'debian':
+        Tree({'patches': Tree({'debian.series': Blob(b'')})})
+    })
+    tree_obj = repo.raw_repo.get(tree_builder.write(repo.raw_repo))
+    env = repo.quilt_env_from_treeish_str(str(tree_obj.id))
+    expected_inside = {
+        'EDITOR': 'true',
+        'QUILT_NO_DIFF_INDEX': '1',
+        'QUILT_NO_DIFF_TIMESTAMPS': '1',
+        'QUILT_PATCHES': 'debian/patches',
+        'QUILT_SERIES': 'debian/patches/debian.series',
+    }
+    for k, v in expected_inside.items():
+        assert env[k] == v
+
+
+def test_repo_derive_env_change(repo):
+    # Changing the dictionary of a GitUbuntuRepository instance env attribute
+    # must not have any effect on the env itself. While this may stretch a
+    # little further than a normal instance property, it's worth enforcing this
+    # as this particular attribute is at particular risk due to how it tends to
+    # be used.
+    e1 = repo.env
+    e1[unittest.mock.sentinel.k] = unittest.mock.sentinel.v
+    assert unittest.mock.sentinel.k not in repo.env
+
+
[e-mail](
+   'description, input_data, old_ubuntu, new_debian, expected',
+   [
+        (
+            'Common case',
+            Repo(
+                commits=[
+                    Commit.from_spec(
+                        name='old/debian'
+                    ),
+                    Commit.from_spec(
+                        parents=[Placeholder('old/debian')],
+                        name='old/ubuntu',
+                        changelog_versions=['1-1ubuntu1', '1-1'],
+                    ),
+                    Commit.from_spec(
+                        parents=[Placeholder('old/debian')],
+                        name='new/debian',
+                        changelog_versions=['2-1', '1-1'],
+                    ),
+                ],
+                tags={
+                    'pkg/import/1-1': Placeholder('old/debian'),
+                    'pkg/import/1-1ubuntu1': Placeholder('old/ubuntu'),
+                    'pkg/import/2-1': Placeholder('new/debian'),
+                },
+            ),
+            'pkg/import/1-1ubuntu1',
+            'pkg/import/2-1',
+            'pkg/import/1-1',
+        ),
+        (
+            'Ubuntu delta based on a NMU',
+            Repo(
+                commits=[
+                    Commit.from_spec(
+                        name='fork_point'
+                    ),
+                    Commit.from_spec(
+                        parents=[Placeholder('fork_point')],
+                        name='old/debian',
+                        changelog_versions=['1-1.1', '1-1'],
+                    ),
+                    Commit.from_spec(
+                        parents=[Placeholder('old/debian')],
+                        name='old/ubuntu',
+                        changelog_versions=['1-1.1ubuntu1', '1-1.1', '1-1'],
+                    ),
+                    Commit.from_spec(
+                        parents=[Placeholder('fork_point')],
+                        name='new/debian',
+                        changelog_versions=['2-1', '1-1'],
+                    ),
+                ],
+                tags={
+                    'pkg/import/1-1': Placeholder('fork_point'),
+                    'pkg/import/1-1.1': Placeholder('old/debian'),
+                    'pkg/import/1-1.1ubuntu1': Placeholder('old/ubuntu'),
+                    'pkg/import/2-1': Placeholder('new/debian'),
+                },
+            ),
+            'pkg/import/1-1.1ubuntu1',
+            'pkg/import/2-1',
+            'pkg/import/1-1.1',
+        ),
+        (
+            'Ubuntu upstream version head of Debian',
+            Repo(
+                commits=[
+                    Commit.from_spec(
+                        name='old/debian'
+                    ),
+                    Commit.from_spec(
+                        parents=[Placeholder('old/debian')],
+                        name='mid_ubuntu',
+                        changelog_versions=['1-1ubuntu1', '1-1'],
+                    ),
+                    Commit.from_spec(
+                        parents=[Placeholder('mid_ubuntu')],
+                        name='old/ubuntu',
+                        changelog_versions=['2-0ubuntu1', '1-1ubuntu1', '1-1'],
+                    ),
+                    Commit.from_spec(
+                        parents=[Placeholder('old/debian')],
+                        name='new/debian',
+                        changelog_versions=['3-1', '1-1'],
+                    ),
+                ],
+                tags={
+                    'pkg/import/1-1': Placeholder('old/debian'),
+                    'pkg/import/1-1ubuntu1': Placeholder('mid_ubuntu'),
+                    'pkg/import/2-0ubuntu1': Placeholder('old/ubuntu'),
+                    'pkg/import/3-1': Placeholder('new/debian'),
+                },
+            ),
+            'pkg/import/2-0ubuntu1',
+            'pkg/import/3-1',
+            'pkg/import/1-1',
+        ),
+   ],
+)
+def test_repo_find_ubuntu_merge(
+   description,
+   repo,
+   input_data,
+   old_ubuntu,
+   new_debian,
+   expected,
+):
+    input_data.write(repo.raw_repo)
+    merge_base = repo.find_ubuntu_merge_base(old_ubuntu)
+
+    assert merge_base
+
+    assert str(
+        repo.get_commitish(merge_base).peel(pygit2.Commit).id
+    ) == str(
+        repo.get_commitish(expected).peel(pygit2.Commit).id
+    )
+
+
+def test_repo_does_cleanup():
+    path = tempfile.mkdtemp()
+    try:
+        repo = target.GitUbuntuRepository(
+            path,
+            delete_on_close=True,
+        )
+        repo.close()
+        assert not os.path.exists(path)
+    finally:
+        shutil.rmtree(path, ignore_errors=True)
+
+
+def test_repo_does_not_cleanup():
+    path = tempfile.mkdtemp()
+    try:
+        repo = target.GitUbuntuRepository(
+            path,
+            delete_on_close=False,
+        )
+        repo.close()
+        assert os.path.exists(path)
+    finally:
+        shutil.rmtree(path, ignore_errors=True)
+
+
[e-mail](
+    [
+        'year',
+        'month',
+        'day',
+        'hours',
+        'minutes',
+        'seconds',
+        'milliseconds',
+        'hour_delta',
+        'expected',
+    ], [
+        (1970, 1, 1, 0, 0, 0, 0, 0, (0, 0)),
+        (1970, 1, 1, 0, 0, 0, 600, 0, (0, 0)),
+        (1970, 1, 1, 1, 0, 0, 0, 1, (0, 60)),
+        (1970, 1, 1, 0, 0, 0, 0, -1, (3600, -60)),
+        (1971, 2, 3, 4, 5, 6, 7, -8, (34430706, -480)),
+    ]
+)
+def test_datetime_to_signature_spec(
+    year,
+    month,