Merge ~rhansen/git-build-recipe:upstream into git-build-recipe:master

[Richard Hansen]

This branch adds a new `upstream` instruction that allows users to specify a revision (branch, tag, whatever) containing the pristine upstream sources. If the recipe contains an `upstream` instruction, the referenced commit will be used instead of the `pristine-tar` branch or the `upstream/<version>` and `upstream-<version>` tags.

This branch also has several refactor, cleanup, and minor bugfix commits to prepare for the new feature.

Fixes bug #2024971

Unmerged commits

7eafc39... by Richard Hansen on 2023-07-07

new `upstream` command to specify location of pristine sources

356a635... by Richard Hansen on 2023-07-08

fix subdirectory existence check

83181c5... by Richard Hansen on 2023-07-08

use `can_have_children` to test if indentation is allowed

This will make it possible to add new commands that support child branches (or
extend existing commands, such as `nest_part`).

0bea610... by Richard Hansen on 2023-07-04

inline the `resolve_commit` method

acf176d... by Richard Hansen on 2023-07-03

ensure that the child branches have been fetched

6debc1a... by Richard Hansen on 2023-07-03

move `resolve_commit` call into `fetch` method

ff10ad5... by Richard Hansen on 2023-07-03

delete redundant call to `resolve_commit`

586d348... by Richard Hansen on 2023-07-03

improve handling of unknown revisions

cc12101... by Richard Hansen on 2023-07-03

move `FetchFailed` exception conversion to the `fetch` method

7c39665... by Richard Hansen on 2023-07-03

move fetch logic to a method on `RecipeBranch`

diff --git a/gitbuildrecipe/deb_util.py b/gitbuildrecipe/deb_util.py
index d0a6666..c3227ba 100644
--- a/gitbuildrecipe/deb_util.py
+++ b/gitbuildrecipe/deb_util.py
@@ -32,13 +32,6 @@ class MissingDependency(Exception):
     pass
 
 
-class NoSuchTag(Exception):
-
-    def __init__(self, tag_name):
-        super().__init__()
-        self.tag_name = tag_name
-
-
 def debian_source_package_name(control_path):
     """Open a debian control file and extract the package name.
 
@@ -48,53 +41,6 @@ def debian_source_package_name(control_path):
         return control["Source"]
 
 
-def extract_upstream_tarball(path, package, version, dest_dir):
-    """Extract the upstream tarball from a Git repository.
-
-    :param path: Path to the Git repository
-    :param package: Package name
-    :param version: Package version
-    :param dest_dir: Destination directory
-    """
-    prefix = "%s_%s.orig.tar." % (package, version)
-    dest_filename = None
-    pristine_tar_list = subprocess.Popen(
-        ["pristine-tar", "list"], stdout=subprocess.PIPE, cwd=path)
-    try:
-        for line in pristine_tar_list.stdout:
-            line = line.decode("UTF-8", errors="replace").rstrip("\n")
-            if line.startswith(prefix):
-                dest_filename = line
-    finally:
-        pristine_tar_list.wait()
-    if dest_filename is not None:
-        subprocess.check_call(
-            ["pristine-tar", "checkout",
-             os.path.abspath(os.path.join(dest_dir, dest_filename))],
-            cwd=path)
-    else:
-        tag_names = ["upstream/%s" % version, "upstream-%s" % version]
-        git_tag_list = subprocess.Popen(
-            ["git", "tag"], stdout=subprocess.PIPE, cwd=path)
-        try:
-            for line in git_tag_list.stdout:
-                line = line.decode("UTF-8", errors="replace").rstrip("\n")
-                if line in tag_names:
-                    tag = line
-                    break
-            else:
-                raise NoSuchTag(tag_names[0])
-        finally:
-            git_tag_list.wait()
-        # Default to .tar.gz
-        dest_filename = prefix + "gz"
-        with open(os.path.join(dest_dir, dest_filename), "wb") as dest:
-            subprocess.check_call(
-                ["git", "archive", "--format=tar.gz",
-                 "--prefix=%s-%s/" % (package, version), tag],
-                stdout=dest, cwd=path)
-
-
 def add_autobuild_changelog_entry(base_branch, basedir, package,
                                   distribution=None, author_name=None,
                                   author_email=None, append_version=None):
diff --git a/gitbuildrecipe/main.py b/gitbuildrecipe/main.py
index 30e6bec..a241744 100644
--- a/gitbuildrecipe/main.py
+++ b/gitbuildrecipe/main.py
@@ -26,11 +26,9 @@ import tempfile
 from debian.changelog import Changelog
 
 from gitbuildrecipe.deb_util import (
-    NoSuchTag,
     add_autobuild_changelog_entry,
     build_source_package,
     debian_source_package_name,
-    extract_upstream_tarball,
     force_native_format,
     get_source_format,
     )
@@ -40,6 +38,7 @@ from gitbuildrecipe.deb_version import (
     substitute_time,
     )
 from gitbuildrecipe.recipe import (
+    NoSuchTag,
     build_tree,
     parse_recipe,
     resolve_revisions,
@@ -159,9 +158,9 @@ def main():
                 current_format == "3.0 (quilt)"):
             # Non-native package
             try:
-                extract_upstream_tarball(
-                    base_branch.path, package_name,
-                    package_version.upstream_version, working_basedir)
+                base_branch.get_upstream_tarball(
+                    package_name, package_version.upstream_version,
+                    working_basedir)
             except NoSuchTag as e:
                 if not args.allow_fallback_to_native:
                     parser.error(
diff --git a/gitbuildrecipe/recipe.py b/gitbuildrecipe/recipe.py
index f932ca7..0ebdfb2 100644
--- a/gitbuildrecipe/recipe.py
+++ b/gitbuildrecipe/recipe.py
@@ -30,16 +30,18 @@ MERGE_INSTRUCTION = "merge"
 NEST_PART_INSTRUCTION = "nest-part"
 NEST_INSTRUCTION = "nest"
 RUN_INSTRUCTION = "run"
+UPSTREAM_INSTRUCTION = "upstream"
 USAGE = {
     MERGE_INSTRUCTION: 'merge NAME BRANCH [REVISION]',
     NEST_INSTRUCTION: 'nest NAME BRANCH TARGET-DIR [REVISION]',
     NEST_PART_INSTRUCTION:
         'nest-part NAME BRANCH SUBDIR [TARGET-DIR [REVISION]]',
     RUN_INSTRUCTION: 'run COMMAND',
+    UPSTREAM_INSTRUCTION: 'upstream NAME BRANCH [REVISION]',
     }
 
 SAFE_INSTRUCTIONS = [
-    MERGE_INSTRUCTION, NEST_PART_INSTRUCTION, NEST_INSTRUCTION]
+    MERGE_INSTRUCTION, NEST_PART_INSTRUCTION, NEST_INSTRUCTION, UPSTREAM_INSTRUCTION]
 
 
 class FormattedError(Exception):
@@ -68,6 +70,22 @@ class FormattedError(Exception):
     __hash__ = Exception.__hash__
 
 
+class NoSuchTag(Exception):
+
+    def __init__(self, tag_name):
+        super().__init__()
+        self.tag_name = tag_name
+
+
+class UnknownRevisionError(Exception):
+
+    def __init__(self, rev):
+        self.rev = rev
+
+    def __str__(self):
+        return str(self.rev)
+
+
 class SubstitutionUnavailable(FormattedError):
 
     _fmt = "Substitution for %(name)s not available: %(reason)s"
@@ -161,7 +179,7 @@ class RevisionVariable(BranchSubstitutionVariable):
     def __init__(self, branch):
         super().__init__(branch.name)
         self.branch = branch
-        self.commit = branch.commit
+        self.commit = branch.commit_for_substvars
 
 
 class RevnoVariable(RevisionVariable):
@@ -299,17 +317,13 @@ def pull_or_clone(base_branch, target_path):
         os.rmdir(target_path)
     if not os.path.exists(target_path):
         os.makedirs(target_path)
-        base_branch.git_call("init")
+        base_branch.git_call("init", "-b", "main")
         for short, base in insteadof.items():
             base_branch.git_call("config", "url.%s.insteadOf" % base, short)
     elif not os.path.exists(os.path.join(target_path, ".git")):
         raise TargetAlreadyExists(target_path)
+    base_branch.fetch()
     try:
-        fetch_branches(base_branch)
-    except subprocess.CalledProcessError as e:
-        raise FetchFailed(e.output)
-    try:
-        base_branch.resolve_commit()
         # Check out the commit hash directly to detach HEAD and ensure
         # commits (eg. by a merge instruction) don't affect substitution
         # variables.
@@ -322,30 +336,6 @@ def pull_or_clone(base_branch, target_path):
         raise CheckoutFailed(e.output)
 
 
-def fetch_branches(child_branch):
-    url = child_branch.url
-    parsed_url = urlparse(url)
-    if not parsed_url.scheme and not parsed_url.path.startswith("/"):
-        url = os.path.abspath(url)
-    # Fetch the remote HEAD.  This may not exist, which is OK as long as the
-    # recipe uses explicit branch names.
-    try:
-        child_branch.git_call(
-            "fetch", url,
-            "HEAD:refs/remotes/%s/HEAD" % child_branch.remote_name,
-            silent=True)
-    except subprocess.CalledProcessError as e:
-        logging.info(e.output)
-        logging.info(
-            "Failed to fetch HEAD; recipe instructions for this repository "
-            "that do not specify a branch name will fail.")
-    # Fetch all remote branches and (implicitly) any tags that reference
-    # commits in those refs. Tags that aren't on a branch won't be fetched.
-    child_branch.git_call(
-        "fetch", url,
-        "refs/heads/*:refs/remotes/%s/*" % child_branch.remote_name)
-
-
 @lru_cache(maxsize=1)
 def _git_version():
     raw_git_version = subprocess.check_output(
@@ -362,9 +352,8 @@ def merge_branch(child_branch, target_path):
     :param target_path: The tree to merge into.
     """
     child_branch.path = target_path
-    fetch_branches(child_branch)
+    child_branch.fetch()
     try:
-        child_branch.resolve_commit()
         cmd = ["merge", "--commit"]
         if _git_version() >= "1:2.9.0":
             cmd.append("--allow-unrelated-histories")
@@ -391,10 +380,9 @@ def nest_part_branch(child_branch, target_path, subpath, target_subdir=None):
     if target_subdir is None:
         target_subdir = os.path.basename(subpath)
     # XXX should handle updating as well
-    assert not os.path.exists(target_subdir)
+    assert not os.path.exists(os.path.join(target_path, target_subdir))
     child_branch.path = target_path
-    fetch_branches(child_branch)
-    child_branch.resolve_commit()
+    child_branch.fetch()
     child_branch.git_call(
         "read-tree", "--prefix", target_subdir, "-u",
         child_branch.commit + ":" + subpath)
@@ -408,7 +396,6 @@ def _build_inner_tree(base_branch, target_path):
         "Retrieving %s'%s' to put at '%s'." %
         (revision_of, base_branch.url, target_path))
     pull_or_clone(base_branch, target_path)
-    base_branch.resolve_commit()
     for instruction in base_branch.child_branches:
         instruction.apply(target_path)
 
@@ -417,8 +404,8 @@ def _resolve_revisions_recurse(new_branch, substitute_branch_vars,
                                if_changed_from=None):
     changed = False
     if substitute_branch_vars is not None:
-        # XXX need to make sure new_branch has been fetched
-        new_branch.resolve_commit()
+        if new_branch.commit is None:
+            new_branch.fetch()
         substitute_branch_vars(new_branch)
     if (if_changed_from is not None and
         (new_branch.revspec is not None or
@@ -499,6 +486,10 @@ class ChildBranch:
 
     can_have_children = False
 
+    @property
+    def instruction(self):
+        raise NotImplementedError("instruction property not set")
+
     def __init__(self, recipe_branch, nest_path=None):
         self.recipe_branch = recipe_branch
         self.nest_path = nest_path
@@ -523,6 +514,8 @@ class ChildBranch:
 
 class CommandInstruction(ChildBranch):
 
+    instruction = RUN_INSTRUCTION
+
     def apply(self, target_path):
         # it's a command
         logging.info("Running '%s' in '%s'." % (self.nest_path, target_path))
@@ -535,6 +528,8 @@ class CommandInstruction(ChildBranch):
 
 class MergeInstruction(ChildBranch):
 
+    instruction = MERGE_INSTRUCTION
+
     def apply(self, target_path):
         revision_of = ""
         if self.recipe_branch.revspec is not None:
@@ -556,6 +551,8 @@ class MergeInstruction(ChildBranch):
 
 class NestPartInstruction(ChildBranch):
 
+    instruction = NEST_PART_INSTRUCTION
+
     def __init__(self, recipe_branch, subpath, target_subdir):
         ChildBranch.__init__(self, recipe_branch)
         self.subpath = subpath
@@ -584,6 +581,8 @@ class NestPartInstruction(ChildBranch):
 
 class NestInstruction(ChildBranch):
 
+    instruction = NEST_INSTRUCTION
+
     can_have_children = True
 
     def apply(self, target_path):
@@ -602,6 +601,47 @@ class NestInstruction(ChildBranch):
             self.recipe_branch.name)
 
 
+class UpstreamInstruction(ChildBranch):
+
+    instruction = UPSTREAM_INSTRUCTION
+
+    can_have_children = True
+
+    def apply(self, target_path):
+        b = self.recipe_branch
+        b.path = target_path
+        if len(b.child_branches) == 0:
+            b.fetch()
+            return
+        is_clean = lambda: b.git_output(
+            "status", "--porcelain", "--ignored", "-u") == ""
+        head_backup = b._get_commit_id("HEAD")
+        clean = is_clean()
+        if not clean:
+            b.git_call("stash", "--all")
+        _build_inner_tree(b, target_path)
+        if not is_clean():
+            b.git_call("stash", "--all")
+            tree = b._get_commit_id("refs/stash@{0}")
+            b.git_call("stash", "pop", "--index")
+            b.git_call("read-tree", tree)
+            b.git_call("commit", "-m", "upstream after child modifications")
+        # The commit(s) made above should not affect any substitution variables.
+        b._commit_for_substvars = b.commit
+        b.commit = b._get_commit_id("HEAD")
+        b.git_call("checkout", head_backup)
+        if not clean:
+            b.git_call("stash", "pop", "--index")
+
+    def as_text(self):
+        b = self.recipe_branch
+        c = self._get_commit_part()
+        return f"{UPSTREAM_INSTRUCTION} {b.name} {b.url}{c}"
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__} {self.recipe_branch.name!r}>"
+
+
 class RecipeBranch:
     """A nested structure that represents a Recipe.
 
@@ -632,6 +672,14 @@ class RecipeBranch:
         self.child_branches = []
         self.commit = None
         self.path = None
+        self._commit_for_substvars = None
+        self._upstream_branch = None
+
+    @property
+    def commit_for_substvars(self):
+        if self._commit_for_substvars is None:
+            return self.commit
+        return self._commit_for_substvars
 
     @property
     def remote_name(self):
@@ -649,6 +697,41 @@ class RecipeBranch:
             raise Exception(
                 "Repository at %s has not been cloned yet" % self.url)
 
+    def fetch(self):
+        url = self.url
+        parsed_url = urlparse(url)
+        if not parsed_url.scheme and not parsed_url.path.startswith("/"):
+            url = os.path.abspath(url)
+        # Fetch the remote HEAD.  This may not exist, which is OK as long as the
+        # recipe uses explicit branch names.
+        try:
+            self.git_call(
+                "fetch", url, "HEAD:refs/remotes/%s/HEAD" % self.remote_name,
+                silent=True)
+        except subprocess.CalledProcessError as e:
+            logging.info(e.output)
+            logging.info(
+                "Failed to fetch HEAD; recipe instructions for this repository "
+                "that do not specify a branch name will fail.")
+        # Fetch all remote branches and (implicitly) any tags that reference
+        # commits in those refs. Tags that aren't on a branch won't be fetched.
+        try:
+            self.git_call(
+                "fetch", url,
+                "refs/heads/*:refs/remotes/%s/*" % self.remote_name)
+        except subprocess.CalledProcessError as e:
+            raise FetchFailed(e.output)
+        try:
+            self.commit = self._get_commit_id(
+                self.remote_name + "/" + self.get_revspec())
+            return
+        except UnknownRevisionError:
+            pass
+        # Not a remote-prefixed ref. Try a global search.
+        # XXX: This allows cross-branch pollution, but we don't have
+        # much choice without reimplementing rev-parse ourselves.
+        self.commit = self._get_commit_id(self.get_revspec())
+
     def git_call(self, *args, **kwargs):
         cmd = ["git", "-C", self._get_git_path()] + list(args)
         silent = kwargs.pop("silent", False)
@@ -675,24 +758,12 @@ class RecipeBranch:
     def get_revspec(self):
         return self.revspec if self.revspec is not None else "HEAD"
 
-    def resolve_commit(self):
-        """Resolve the commit for this branch."""
-        # Capturing stderr is a bit dodgy, but it's the most convenient way
-        # to capture it for any exceptions.  We know that git rev-parse does
-        # not write to stderr on success.
+    def _get_commit_id(self, rev):
         try:
-            self.commit = self.git_output(
-                "rev-parse", "%s/%s" % (self.remote_name, self.get_revspec()),
-                stderr=subprocess.STDOUT).rstrip("\n")
-            return
-        except subprocess.CalledProcessError:
-            pass
-        # Not a remote-prefixed ref. Try a global search.
-        # XXX: This allows cross-branch pollution, but we don't have
-        # much choice without reimplementing rev-parse ourselves.
-        self.commit = self.git_output(
-            "rev-parse", self.get_revspec(),
-            stderr=subprocess.STDOUT).rstrip("\n")
+            return self.git_output(
+                "rev-parse", "--revs-only", "--verify", "-q", rev).rstrip("\n")
+        except subprocess.CalledProcessError as e:
+            raise UnknownRevisionError(rev) from e
 
     def merge_branch(self, branch):
         """Merge a child branch into this one.
@@ -733,6 +804,19 @@ class RecipeBranch:
         """
         self.child_branches.append(CommandInstruction(None, command))
 
+    def upstream_branch(self, branch):
+        """Mark a branch as containing the original pristine sources.
+
+        :param branch: The `RecipeBranch` referencing the pristine sources.
+        """
+        if self.name is not None:
+            raise Exception(
+                "the upstream command only applies to the base branch")
+        if self._upstream_branch is not None:
+            raise Exception("upstream already set for the base branch")
+        self.child_branches.append(UpstreamInstruction(branch))
+        self._upstream_branch = branch
+
     def different_shape_to(self, other_branch):
         """Test whether the name, url, and child_branches are the same."""
         if self.name != other_branch.name:
@@ -851,6 +935,65 @@ class BaseRecipeBranch(RecipeBranch):
             RecipeParser(manifest).parse()
         return manifest
 
+    def get_upstream_tarball(self, package, version, dest_dir):
+        """Generate the upstream tarball (*.orig.tar.*).
+
+        :param package: Package name
+        :param version: Package version
+        :param dest_dir: Destination directory
+        """
+        prefix = "%s_%s.orig.tar." % (package, version)
+        if self._upstream_branch is not None:
+            # self._upstream_branch.fetch() has already been called, and it
+            # should NOT be called again here otherwise it will undo any changes
+            # made by child instructions.
+            dest_filename = prefix + "gz"
+            tarball = os.path.abspath(os.path.join(dest_dir, dest_filename))
+            # With `Format: 1.0` packages, dpkg-source does not delete the
+            # debian directory (if present in the *.orig.tar.gz) before applying
+            # the *.diff.gz.  Exclude the debian directory when generating the
+            # orig archive to avoid problems applying the patch.  (The diff.gz
+            # can't delete files, only empty them.)  This isn't necessary for
+            # `Format: 3.0 (quilt)` packages, but it doesn't really hurt either.
+            # If the user is concerned with perfect representation of the
+            # upstream sources with `Format: 3.0 (quilt)` packages, they should
+            # use pristine-tar.
+            self.git_call(
+                "archive", f"--output={tarball}",
+                f"--prefix={package}-{version}/", self._upstream_branch.commit,
+                ":(exclude)debian")
+            return
+        dest_filename = None
+        pristine_tar_list = subprocess.Popen(
+            ["pristine-tar", "list"], stdout=subprocess.PIPE, cwd=self.path)
+        try:
+            for line in pristine_tar_list.stdout:
+                line = line.decode("UTF-8", errors="replace").rstrip("\n")
+                if line.startswith(prefix):
+                    dest_filename = line
+        finally:
+            pristine_tar_list.wait()
+        if dest_filename is not None:
+            subprocess.check_call(
+                ["pristine-tar", "checkout",
+                 os.path.abspath(os.path.join(dest_dir, dest_filename))],
+                cwd=self.path)
+        else:
+            tag_names = ["upstream/%s" % version, "upstream-%s" % version]
+            for line in self.git_output("tag").rstrip("\n").split("\n"):
+                if line in tag_names:
+                    tag = line
+                    break
+            else:
+                raise NoSuchTag(tag_names[0])
+            # Default to .tar.gz
+            dest_filename = prefix + "gz"
+            with open(os.path.join(dest_dir, dest_filename), "wb") as dest:
+                subprocess.check_call(
+                    ["git", "archive", "--format=tar.gz",
+                     "--prefix=%s-%s/" % (package, version), tag],
+                    stdout=dest, cwd=self.path)
+
 
 class RecipeParseError(FormattedError):
 
@@ -887,7 +1030,7 @@ class RecipeParser:
     eol_char = "\n"
     digit_chars = ("0", "1", "2", "3", "4", "5", "6", "7", "8", "9")
 
-    NEWEST_VERSION = 0.4
+    NEWEST_VERSION = 0.5
 
     def __init__(self, f):
         """Create a `RecipeParser`.
@@ -922,10 +1065,44 @@ class RecipeParser:
         self.seen_paths = {".": 1}
         version, deb_version = self.parse_header()
         self.version = version
+
+        # active_instructions contains the ChildBranch objects in the current
+        # instruction's parent path, in ancestry order.  Thus,
+        # active_instructions[-1] always refers to the current instruction's
+        # parent instruction.  For example, consider the following recipe:
+        #
+        #     # git-build-recipe format 0.4 deb-version 1.0-1
+        #     http://example.test/repo.git
+        #     nest nest1 http://example.test/nest1.git nest1
+        #       nest nest2 http://example.test/nest2.git nest2
+        #     nest nest3 http://example.test/nest3.git nest3
+        #       nest nest4 http://example.test/nest4.git nest4
+        #         nest nest5 http://example.test/nest5.git nest5
+        #
+        # When the nest5 line is processed, active_instructions will contain the
+        # following entries:
+        #
+        #   0. None (This entry is for the base branch, which doesn't have a
+        #      corresponding ChildBranch object.)
+        #   1. <NestInstruction 'nest3'>
+        #   2. <NestInstruction 'nest4'>
+        active_instructions = []
         last_instruction = None
+
+        # active_branches has the same structure as active_instructions, except
+        # it holds the RecipeBranch objects in the parent path.
+        # active_branches[-1] always refers to the parent instruction's branch.
+        # With the above example recipe, active_branches would hold the
+        # following entries when processing the nest5 line:
+        #
+        #   0. <BaseRecipeBranch None>
+        #   1. <RecipeBranch 'nest3'>
+        #   2. <RecipeBranch 'nest4'>
         active_branches = []
         last_branch = None
+
         while self.line_index < len(self.lines):
+            assert len(active_instructions) == len(active_branches)
             if self.is_blankline():
                 self.new_line()
                 continue
@@ -935,24 +1112,34 @@ class RecipeParser:
                 continue
             old_indent_level = self.parse_indent()
             if old_indent_level is not None:
-                if (old_indent_level < self.current_indent_level
-                    and last_instruction != NEST_INSTRUCTION):
-                    self.throw_parse_error(
-                        "Not allowed to indent unless after a '%s' line" %
-                        NEST_INSTRUCTION)
                 if old_indent_level < self.current_indent_level:
+                    if len(active_instructions) == 0:
+                        self.throw_parse_error(
+                            "indentation of base branch not allowed")
+                    p = last_instruction
+                    if p is None:
+                        self.throw_parse_error(
+                            "indentation under base branch not allowed")
+                    if not p.can_have_children:
+                        self.throw_parse_error(
+                            f"indentation under '{p.instruction}' not allowed")
+                    active_instructions.append(last_instruction)
                     active_branches.append(last_branch)
                 else:
                     unindent = self.current_indent_level - old_indent_level
+                    active_instructions = active_instructions[:unindent]
                     active_branches = active_branches[:unindent]
-            if last_instruction is None:
+            if len(active_instructions) == 0:
                 url = self.take_to_whitespace("branch to start from")
                 revspec = self.parse_optional_revspec()
                 self.new_line()
                 last_branch = BaseRecipeBranch(
                     url, deb_version, self.version, revspec=revspec)
                 active_branches = [last_branch]
-                last_instruction = ""
+                # The base branch doesn't have a corresponding ChildBranch, so
+                # None is inserted in the base branch's slot (index 0).
+                last_instruction = None
+                active_instructions = [None]
             else:
                 instruction = self.parse_instruction(
                     permitted_instructions=permitted_instructions)
@@ -986,7 +1173,9 @@ class RecipeParser:
                     elif instruction == NEST_PART_INSTRUCTION:
                         active_branches[-1].nest_part_branch(
                             last_branch, path, target_subdir)
-                last_instruction = instruction
+                    elif instruction == UPSTREAM_INSTRUCTION:
+                        active_branches[-1].upstream_branch(last_branch)
+                last_instruction = active_branches[-1].child_branches[-1]
         if len(active_branches) == 0:
             self.throw_parse_error("Empty recipe")
         return active_branches[0]
@@ -1009,21 +1198,19 @@ class RecipeParser:
         return version, deb_version
 
     def parse_instruction(self, permitted_instructions=None):
-        if self.version < 0.2:
-            options = (MERGE_INSTRUCTION, NEST_INSTRUCTION)
-            options_str = "'%s' or '%s'" % options
-        elif self.version < 0.3:
-            options = (MERGE_INSTRUCTION, NEST_INSTRUCTION, RUN_INSTRUCTION)
-            options_str = "'%s', '%s', or '%s'" % options
-        else:
-            options = (
-                MERGE_INSTRUCTION, NEST_INSTRUCTION, NEST_PART_INSTRUCTION,
-                RUN_INSTRUCTION)
-            options_str = "'%s', '%s', '%s', or '%s'" % options
+        options = [MERGE_INSTRUCTION, NEST_INSTRUCTION]
+        if self.version >= 0.2:
+            options.append(RUN_INSTRUCTION)
+        if self.version >= 0.3:
+            options.append(NEST_PART_INSTRUCTION)
+        if self.version >= 0.5:
+            options.append(UPSTREAM_INSTRUCTION)
+        options.sort()
+        options_str = ", ".join(f"'{o}'" for o in options)
         instruction = self.peek_to_whitespace()
         if instruction is None:
             self.throw_parse_error(
-                "End of line while looking for %s" % options_str)
+                "End of line while looking for one of: %s" % options_str)
         if instruction in options:
             if permitted_instructions is not None:
                 if instruction not in permitted_instructions:
@@ -1034,7 +1221,7 @@ class RecipeParser:
             self.take_chars(len(instruction))
             return instruction
         self.throw_parse_error(
-            "Expecting %s, got '%s'" % (options_str, instruction))
+            "Expecting one of %s; got '%s'" % (options_str, instruction))
 
     def parse_branch_id(self, instruction):
         self.parse_whitespace("the branch id", instruction=instruction)
diff --git a/gitbuildrecipe/tests/__init__.py b/gitbuildrecipe/tests/__init__.py
index d968f5b..e6cfde0 100644
--- a/gitbuildrecipe/tests/__init__.py
+++ b/gitbuildrecipe/tests/__init__.py
@@ -29,7 +29,7 @@ class GitRepository:
         if not os.path.exists(path):
             os.makedirs(path)
         if allow_create and not os.path.exists(os.path.join(path, ".git")):
-            self._git_call("init", "-q")
+            self._git_call("init", "-b", "main")
 
     def _git_call(self, *args, **kwargs):
         subprocess.check_call(["git", "-C", self.path] + list(args), **kwargs)
@@ -55,7 +55,7 @@ class GitRepository:
         env = os.environ.copy()
         if date is not None:
             env["GIT_COMMITTER_DATE"] = date
-        self._git_call("commit", "-q", "--allow-empty", "-m", message, env=env)
+        self._git_call("commit", "--allow-empty", "-m", message, env=env)
         return self.last_revision()
 
     def branch(self, branch_name, commit):
@@ -76,7 +76,7 @@ class GitRepository:
             "log", "-1", "--format=%P", commit).rstrip("\n").split()
 
     def clone_to(self, new_path):
-        subprocess.check_call(["git", "clone", "-q", self.path, new_path])
+        subprocess.check_call(["git", "clone", self.path, new_path])
         return GitRepository(new_path, allow_create=False)
 
     def build_tree(self, shape):
diff --git a/gitbuildrecipe/tests/test_deb_version.py b/gitbuildrecipe/tests/test_deb_version.py
index 662e811..9c005f0 100644
--- a/gitbuildrecipe/tests/test_deb_version.py
+++ b/gitbuildrecipe/tests/test_deb_version.py
@@ -33,6 +33,7 @@ from gitbuildrecipe.recipe import (
     BaseRecipeBranch,
     build_tree,
     RecipeBranch,
+    RecipeParser,
     resolve_revisions,
     )
 from gitbuildrecipe.tests import (
@@ -231,7 +232,7 @@ class ResolveRevisionsTests(GitTestCase):
     def test_substitute_revno(self):
         source = GitRepository("source")
         source.commit("one")
-        source._git_call("checkout", "-q", "-b", "branch")
+        source._git_call("checkout", "-b", "branch")
         source.build_tree(["a"])
         source.add(["a"])
         source.commit("two")
@@ -240,10 +241,9 @@ class ResolveRevisionsTests(GitTestCase):
         resolve_revisions(
             branch1, substitute_branch_vars=substitute_branch_vars)
         self.assertEqual("foo-3", branch1.deb_version)
-        source._git_call("checkout", "-q", "master")
+        source._git_call("checkout", "main")
         source._git_call(
-            "merge", "-q", "--no-ff", "--commit", "-m", "merge branch",
-            "branch")
+            "merge", "--no-ff", "--commit", "-m", "merge branch", "branch")
         branch2 = BaseRecipeBranch("source", "foo-{revno}", 0.1)
         resolve_revisions(
             branch2, substitute_branch_vars=substitute_branch_vars)
@@ -254,13 +254,13 @@ class ResolveRevisionsTests(GitTestCase):
         # the base branch was committed to by instructions such as merge.
         source = GitRepository("source")
         source.commit("one")
-        source._git_call("checkout", "-q", "-b", "branch")
+        source._git_call("checkout", "-b", "branch")
         source.build_tree(["a"])
         source.add(["a"])
         source.commit("two")
         source.commit("three")
         branch1 = BaseRecipeBranch(
-            "source", "foo-{revno}+{revno:branch}", 0.1, revspec="master")
+            "source", "foo-{revno}+{revno:branch}", 0.1, revspec="main")
         branch2 = RecipeBranch("branch", "source", revspec="branch")
         branch1.merge_branch(branch2)
         build_tree(branch1, "target")
@@ -268,6 +268,23 @@ class ResolveRevisionsTests(GitTestCase):
             branch1, substitute_branch_vars=substitute_branch_vars)
         self.assertEqual("foo-1+3", branch1.deb_version)
 
+    def test_upstream(self):
+        source = GitRepository("source")
+        source.commit("one")
+        source._git_call("checkout", "-b", "debianized")
+        source.build_tree(["a"])
+        source.add(["a"])
+        source.commit("two")
+        source._git_call("checkout", "main")
+        recipe = (
+            "# git-build-recipe format 0.5 deb-version {revno:pristine}-{revno}\n"
+            "source debianized\n"
+            "upstream pristine source\n"
+        )
+        branch = RecipeParser(recipe).parse()
+        resolve_revisions(branch, substitute_branch_vars=substitute_branch_vars)
+        self.assertEqual(branch.deb_version, "1-2")
+
 
 class DebUpstreamVariableTests(GitTestCase):
 
@@ -398,21 +415,21 @@ class RecipeBranchTests(GitTestCase):
         self.assertEqual("1", base_branch.deb_version)
         base_branch = BaseRecipeBranch(
             "base_url", "{revdate}", 0.4, revspec=commit1)
-        base_branch.resolve_commit()
+        base_branch.fetch()
         substitute_branch_vars(base_branch, base_branch)
         self.assertEqual("20150101", base_branch.deb_version)
         base_branch = BaseRecipeBranch(
             "base_url", "{revdate}", 0.4, revspec=commit1)
-        base_branch.resolve_commit()
+        base_branch.fetch()
         child_branch = RecipeBranch("foo", "base_url", revspec=commit2)
-        child_branch.resolve_commit()
+        child_branch.fetch()
         substitute_branch_vars(base_branch, child_branch)
         self.assertEqual("{revdate}", base_branch.deb_version)
         substitute_branch_vars(base_branch, child_branch)
         self.assertEqual("{revdate}", base_branch.deb_version)
         base_branch = BaseRecipeBranch(
             "base_url", "{revdate:foo}", 0.4, revspec=commit1)
-        base_branch.resolve_commit()
+        base_branch.fetch()
         substitute_branch_vars(base_branch, child_branch)
         self.assertEqual("20150102", base_branch.deb_version)
 
diff --git a/gitbuildrecipe/tests/test_functional.py b/gitbuildrecipe/tests/test_functional.py
index 56fd216..dc796d3 100644
--- a/gitbuildrecipe/tests/test_functional.py
+++ b/gitbuildrecipe/tests/test_functional.py
@@ -195,8 +195,8 @@ class FunctionalBuilderTests(GitTestCase):
 
     def make_upstream_version(self, source, package_name, version, contents,
                               pristine_tar_format=None):
-        source._git_call("checkout", "-q", "--orphan", "upstream")
-        source._git_call("rm", "-qrf", ".")
+        source._git_call("checkout", "--orphan", "upstream")
+        source._git_call("rm", "-rf", ".")
         source.build_tree_contents(contents)
         source.add(["."])
         commit = source.commit("import upstream %s" % version)
@@ -221,12 +221,11 @@ class FunctionalBuilderTests(GitTestCase):
             stderr=subprocess.DEVNULL, cwd=source.path)
         tarfile_sha1 = sha1_file_by_name(tarfile_path)
         source.tag("upstream/%s" % version, commit)
-        source._git_call("checkout", "-q", "master")
+        source._git_call("checkout", "main")
         return tarfile_sha1
 
-    def make_simple_package(self, path):
-        source = GitRepository(path)
-        source.build_tree(["a", "debian/"])
+    def add_simple_package_files(self, source):
+        source.build_tree(["debian/"])
         cl_contents = ("package (0.1-1) unstable; urgency=low\n  * foo\n"
                     " -- maint <[e-mail]>  Tue, 04 Aug 2009 "
                     "10:03:10 +0100\n")
@@ -237,7 +236,13 @@ class FunctionalBuilderTests(GitTestCase):
                 "Package: package\nArchitecture: all\n"),
             ("debian/changelog", cl_contents)
             ])
-        source.add(["a", "debian/rules", "debian/control", "debian/changelog"])
+        source.add(["debian/rules", "debian/control", "debian/changelog"])
+
+    def make_simple_package(self, path):
+        source = GitRepository(path)
+        source.build_tree(["a"])
+        source.add(["a"])
+        self.add_simple_package_files(source)
         source.commit("one")
         return source
 
@@ -579,3 +584,194 @@ class FunctionalBuilderTests(GitTestCase):
         out, err = self.run_recipe(
             "--allow-fallback-to-native test.recipe working", retcode=1)
         self.assertIn("Unknown source format 2.0\n", err)
+
+    def test_upstream_command_default_branch(self):
+        source = GitRepository("source")
+        # The debian/ directory should be filtered out when generating the orig
+        # tarball, but not the foo/debian/ directory.
+        files = ["a", "debian/a", "foo/debian/a"]
+        source.build_tree(files)
+        source.add(files)
+        source.commit("pristine sources")
+        source._git_call("checkout", "-b", "debianized")
+        source._git_call("rm", "-rf", "debian")
+        self.add_simple_package_files(source)
+        source.commit("debianized sources")
+        source._git_call("checkout", "main")
+        with open("package-0.1.recipe", "w") as f:
+            f.write(
+                "# git-build-recipe format 0.5 deb-version 0.1-1\n"
+                "source debianized\n"
+                "upstream upstream source\n")
+        self.run_recipe("package-0.1.recipe working")
+        self.assertThat("working/package_0.1.orig.tar.gz", PathExists())
+        self.assertThat("working/package_0.1-1.diff.gz", PathExists())
+        os.mkdir("extracted-orig")
+        subprocess.check_call(
+            ["tar", "xvfa", "../working/package_0.1.orig.tar.gz"],
+            cwd="extracted-orig")
+        self.assertThat("extracted-orig/package-0.1/a", PathExists())
+        self.assertThat("extracted-orig/package-0.1/debian", Not(PathExists()))
+        self.assertThat("extracted-orig/package-0.1/foo/debian/a", PathExists())
+
+    def test_upstream_command_specific_branch(self):
+        source = GitRepository("source")
+        # The debian/ directory should be filtered out when generating the orig
+        # tarball, but not the foo/debian/ directory.
+        files = ["a", "debian/a", "foo/debian/a"]
+        source.build_tree(files)
+        source.add(files)
+        source.commit("pristine sources")
+        source._git_call("checkout", "-b", "debianized")
+        source._git_call("rm", "-rf", "debian")
+        self.add_simple_package_files(source)
+        source.commit("debianized sources")
+        with open("package-0.1.recipe", "w") as f:
+            f.write(
+                "# git-build-recipe format 0.5 deb-version 0.1-1\n"
+                "source\n"
+                "upstream upstream source main\n")
+        self.run_recipe("package-0.1.recipe working")
+        self.assertThat("working/package_0.1.orig.tar.gz", PathExists())
+        self.assertThat("working/package_0.1-1.diff.gz", PathExists())
+        os.mkdir("extracted-orig")
+        subprocess.check_call(
+            ["tar", "xvfa", "../working/package_0.1.orig.tar.gz"],
+            cwd="extracted-orig")
+        self.assertThat("extracted-orig/package-0.1/a", PathExists())
+        self.assertThat("extracted-orig/package-0.1/debian", Not(PathExists()))
+        self.assertThat("extracted-orig/package-0.1/foo/debian/a", PathExists())
+
+    def test_upstream_command_bad_repo(self):
+        source = GitRepository("source")
+        files = ["a"]
+        source.build_tree(files)
+        source.add(files)
+        self.add_simple_package_files(source)
+        source.commit("one")
+        with open("package-0.1.recipe", "w") as f:
+            f.write(
+                "# git-build-recipe format 0.5 deb-version 0.1-1\n"
+                "source\n"
+                "upstream upstream missingupstream\n")
+        _, err = self.run_recipe("package-0.1.recipe working", retcode=1)
+        self.assertIn("missingupstream", err)
+
+    def test_upstream_command_bad_rev(self):
+        source = GitRepository("source")
+        files = ["a"]
+        source.build_tree(files)
+        source.add(files)
+        self.add_simple_package_files(source)
+        source.commit("one")
+        with open("package-0.1.recipe", "w") as f:
+            f.write(
+                "# git-build-recipe format 0.5 deb-version 0.1-1\n"
+                "source\n"
+                "upstream upstream source missingrev\n")
+        _, err = self.run_recipe("package-0.1.recipe working", retcode=1)
+        self.assertIn("missingrev", err)
+
+    def test_upstream_command_with_child_clean(self):
+        """Child branch that does not dirty the working dir or index."""
+        source = GitRepository("source")
+        for f in ["a", "b"]:
+            source.build_tree([f])
+            source.add([f])
+            source.commit(f)
+        self.add_simple_package_files(source)
+        source.commit("packaging")
+        source._git_call("checkout", "-b", "tomerge", "HEAD^^")
+        source.build_tree(["c"])
+        source.add(["c"])
+        source.commit("c")
+        with open("package-0.1.recipe", "w") as f:
+            f.write(
+                "# git-build-recipe format 0.5 deb-version 0.1-{revno:upstream}\n"
+                "source main\n"
+                "upstream upstream source main\n"
+                # The merge instruction creates a commit, so the working
+                # directory and index should be clean.  That commit should not
+                # affect the substitution variables.
+                "  merge merge source tomerge")
+        self.run_recipe("package-0.1.recipe working")
+        self.run_recipe("package-0.1.recipe working")
+        cl = changelog.Changelog(self._get_file_contents(
+            "working/package-0.1/debian/changelog"))
+        self.assertEqual("0.1-3", str(cl._blocks[0].version))
+        self.assertThat("working/package_0.1.orig.tar.gz", PathExists())
+        self.assertThat("working/package_0.1-3.diff.gz", PathExists())
+        os.mkdir("extracted-orig")
+        subprocess.check_call(
+            ["tar", "xvfa", "../working/package_0.1.orig.tar.gz"],
+            cwd="extracted-orig")
+        self.assertThat("extracted-orig/package-0.1/a", PathExists())
+        self.assertThat("extracted-orig/package-0.1/b", PathExists())
+        self.assertThat("extracted-orig/package-0.1/debian", Not(PathExists()))
+
+    def test_upstream_command_with_child_dirty(self):
+        """Child branch that modifies the working dir/index without commit."""
+        source = GitRepository("source")
+        source.build_tree(["a"])
+        source.add(["a"])
+        self.add_simple_package_files(source)
+        source.commit("one")
+        nested = GitRepository("nested")
+        nested.build_tree(["nestsrc/b"])
+        nested.add(["nestsrc/b"])
+        nested.commit("to nest")
+        with open("package-0.1.recipe", "w") as f:
+            f.write(
+                "# git-build-recipe format 0.5 deb-version 0.1-{revno:upstream}\n"
+                "source main\n"
+                "upstream upstream source main\n"
+                # The nest-part instruction modifies the index (and working
+                # directory to match) without committing, so it will be dirty.
+                # A commit will be created to hold the dirty contents; that
+                # commit should not affect the substitution variables.
+                "  nest-part nested nested nestsrc nestdst\n")
+        self.run_recipe("package-0.1.recipe working")
+        cl = changelog.Changelog(self._get_file_contents(
+            "working/package-0.1/debian/changelog"))
+        self.assertEqual("0.1-1", str(cl._blocks[0].version))
+        self.assertThat("working/package_0.1.orig.tar.gz", PathExists())
+        self.assertThat("working/package_0.1-1.diff.gz", PathExists())
+        os.mkdir("extracted-orig")
+        subprocess.check_call(
+            ["tar", "xvfa", "../working/package_0.1.orig.tar.gz"],
+            cwd="extracted-orig")
+        self.assertThat("extracted-orig/package-0.1/a", PathExists())
+        self.assertThat("extracted-orig/package-0.1/debian", Not(PathExists()))
+        self.assertThat("extracted-orig/package-0.1/nestdst/b", PathExists())
+
+    def test_upstream_command_with_child_and_base_dirty(self):
+        """The working dir or index is dirty before the upstream is applied."""
+        source = GitRepository("source")
+        source.build_tree(["a"])
+        source.add(["a"])
+        self.add_simple_package_files(source)
+        source.commit("one")
+        nested = GitRepository("nested")
+        nested.build_tree(["nestsrc/b"])
+        nested.add(["nestsrc/b"])
+        nested.commit("to nest")
+        with open("package-0.1.recipe", "w") as f:
+            f.write(
+                "# git-build-recipe format 0.5 deb-version 0.1-1\n"
+                "source main\n"
+                "nest-part nested-source nested nestsrc nestdst-source\n"
+                "upstream upstream source main\n"
+                # The nest-part instruction modifies the index (and working
+                # directory to match) without committing, so it will be dirty.
+                "  nest-part nested-upstream nested nestsrc nestdst-upstream\n")
+        self.run_recipe("package-0.1.recipe working")
+        self.assertThat("working/package_0.1.orig.tar.gz", PathExists())
+        self.assertThat("working/package_0.1-1.diff.gz", PathExists())
+        os.mkdir("extracted-orig")
+        subprocess.check_call(
+            ["tar", "xvfa", "../working/package_0.1.orig.tar.gz"],
+            cwd="extracted-orig")
+        self.assertThat("extracted-orig/package-0.1/a", PathExists())
+        self.assertThat("extracted-orig/package-0.1/debian", Not(PathExists()))
+        self.assertThat(
+            "extracted-orig/package-0.1/nestdst-upstream/b", PathExists())
diff --git a/gitbuildrecipe/tests/test_recipe.py b/gitbuildrecipe/tests/test_recipe.py
index bfc6452..cb051f3 100644
--- a/gitbuildrecipe/tests/test_recipe.py
+++ b/gitbuildrecipe/tests/test_recipe.py
@@ -39,6 +39,7 @@ from gitbuildrecipe.recipe import (
     SAFE_INSTRUCTIONS,
     TargetAlreadyExists,
     USAGE,
+    UnknownRevisionError,
     )
 from gitbuildrecipe.tests import (
     GitRepository,
@@ -144,9 +145,9 @@ class RecipeParserTests(GitTestCase):
                 "# git-build-recipe format 0.1 deb-version 1 foo")
 
     def tests_rejects_indented_base_branch(self):
-        self.assertParseError(2, 3, "Not allowed to indent unless after "
-                "a 'nest' line", self.get_recipe,
-                self.basic_header + "  http://foo.org/")
+        self.assertParseError(
+            2, 3, "indentation of base branch not allowed", self.get_recipe,
+            self.basic_header + "  http://foo.org/")
 
     def tests_rejects_text_after_base_branch(self):
         self.assertParseError(2, 19, "Expecting the end of the line, "
@@ -154,8 +155,8 @@ class RecipeParserTests(GitTestCase):
                 self.basic_header + "http://foo.org/ 2 foo")
 
     def tests_rejects_unknown_instruction(self):
-        self.assertParseError(3, 1, "Expecting 'merge', 'nest', 'nest-part', "
-                "or 'run', got 'cat'", self.get_recipe,
+        self.assertParseError(3, 1, "Expecting one of 'merge', 'nest', 'nest-part', 'run'; "
+                "got 'cat'", self.get_recipe,
                 self.basic_header + "http://foo.org/\n" + "cat")
 
     def test_rejects_merge_no_name(self):
@@ -225,15 +226,14 @@ class RecipeParserTests(GitTestCase):
                 self.basic_header_and_branch + "nest foo url bar 2 baz")
 
     def test_rejects_indent_after_first_branch(self):
-        self.assertParseError(3, 3, "Not allowed to indent unless after "
-                "a 'nest' line", self.get_recipe,
-                self.basic_header_and_branch + "  nest foo url bar")
+        self.assertParseError(
+            3, 3, "indentation under base branch not allowed", self.get_recipe,
+            self.basic_header_and_branch + "  nest foo url bar")
 
     def test_rejects_indent_after_merge(self):
-        self.assertParseError(4, 3, "Not allowed to indent unless after "
-                "a 'nest' line", self.get_recipe,
-                self.basic_header_and_branch + "merge foo url\n"
-                + "  nest baz url bar")
+        self.assertParseError(
+            4, 3, "indentation under 'merge' not allowed", self.get_recipe,
+            self.basic_header_and_branch + "merge foo url\n  nest baz url bar")
 
     def test_rejects_tab_indent(self):
         self.assertParseError(4, 3, "Indents may not be done by tabs",
@@ -466,14 +466,14 @@ class RecipeParserTests(GitTestCase):
     def test_old_format_rejects_run(self):
         header = ("# git-build-recipe format 0.1 deb-version "
                 + self.deb_version +"\n")
-        self.assertParseError(3, 1, "Expecting 'merge' or 'nest', got 'run'"
+        self.assertParseError(3, 1, "Expecting one of 'merge', 'nest'; got 'run'"
                 , self.get_recipe, header + "http://foo.org/\n"
                 + "run touch test \n")
 
     def test_old_format_rejects_nest_part(self):
         header = ("# git-build-recipe format 0.2 deb-version "
                 + self.deb_version +"\n")
-        self.assertParseError(3, 1, "Expecting 'merge', 'nest', or 'run', "
+        self.assertParseError(3, 1, "Expecting one of 'merge', 'nest', 'run'; "
                 "got 'nest-part'" , self.get_recipe,
                 header + "http://foo.org/\nnest-part packaging foo test \n")
 
@@ -522,6 +522,52 @@ class RecipeParserTests(GitTestCase):
             " ./foo/../..", NEST_INSTRUCTION, self.get_recipe,
             self.basic_header_and_branch + "nest nest url ./foo/../..\n")
 
+    def test_upstream_default_branch(self):
+        recipe = (
+            "# git-build-recipe format 0.5 deb-version 1.0-1\n"
+            "http://exmaple.test/repo.git\n"
+            "upstream pristine http://example.test/upstream.git\n"
+        )
+        base = self.get_recipe(recipe)
+        self.assertEqual(str(base), recipe)
+
+    def test_upstream_specific_branch(self):
+        recipe = (
+            "# git-build-recipe format 0.5 deb-version 1.0-1\n"
+            "http://exmaple.test/repo.git\n"
+            "upstream pristine http://example.test/upstream.git somebranch\n"
+        )
+        base = self.get_recipe(recipe)
+        self.assertEqual(str(base), recipe)
+
+    def test_upstream_with_child(self):
+        recipe = (
+            "# git-build-recipe format 0.5 deb-version 1.0-1\n"
+            "http://exmaple.test/repo.git\n"
+            "upstream pristine http://example.test/upstream.git somebranch\n"
+            "  merge tomerge http://example.test/tomerge.git\n"
+        )
+        base = self.get_recipe(recipe)
+        self.assertEqual(str(base), recipe)
+
+    def test_error_upstream_as_child(self):
+        recipe = (
+            "# git-build-recipe format 0.5 deb-version 1.0-1\n"
+            "http://exmaple.test/repo.git\n"
+            "nest nested http://example.test/nest.git foo\n"
+            "  upstream pristine http://example.test/upstream.git somebranch\n"
+        )
+        self.assertRaises(Exception, self.get_recipe, recipe)
+
+    def test_error_upstream_twice(self):
+        recipe = (
+            "# git-build-recipe format 0.5 deb-version 1.0-1\n"
+            "http://exmaple.test/repo.git\n"
+            "upstream pristine http://example.test/upstream.git somebranch\n"
+            "upstream other http://example.test/upstream.git somebranch\n"
+        )
+        self.assertRaises(Exception, self.get_recipe, recipe)
+
 
 class BuildTreeTests(GitTestCase):
 
@@ -896,14 +942,12 @@ class BuildTreeTests(GitTestCase):
         source.build_tree(["a"])
         source.add(["a"])
         commit = source.commit("one")
-        source.branch("source/master", commit)
         source.set_head("refs/heads/nonexistent")
-        base_branch = BaseRecipeBranch(
-            "source", "1", 0.2, revspec="source/master")
+        base_branch = BaseRecipeBranch("source", "1", 0.2, revspec="main")
         pull_or_clone(base_branch, "target")
         target = GitRepository("target", allow_create=False)
         self.assertEqual(commit, target.last_revision())
-        self.assertEqual(commit, target.rev_parse("source/master"))
+        self.assertEqual(commit, target.rev_parse("source/main"))
 
     def test_build_tree_runs_commands(self):
         source = GitRepository("source")
@@ -917,15 +961,14 @@ class BuildTreeTests(GitTestCase):
         self.assertEqual(commit, target.rev_parse("HEAD"))
         self.assertEqual(commit, base_branch.commit)
 
-    def test_error_on_merge_revspec(self):
-        # See bug 416950
+    def test_error_on_unknown_revision(self):
         source = GitRepository("source")
         source.commit("one")
         base_branch = BaseRecipeBranch("source", "1", 0.2)
         merged_branch = RecipeBranch("merged", "source", revspec="debian")
         base_branch.merge_branch(merged_branch)
-        e = self.assertRaises(MergeFailed, build_tree, base_branch, "target")
-        self.assertIn("ambiguous argument 'debian'", str(e))
+        e = self.assertRaises(UnknownRevisionError, build_tree, base_branch, "target")
+        self.assertIn("debian", str(e))
 
 
 class StringifyTests(GitTestCase):