Dear Maintainer,

I would like to import the first version of an upstream source into
a fresh gbp-maintained debian package. I have the usual debian
branch files under debian/ prepped, the working tree is ready for
an uscan.

  $ git ls-tree HEAD
  040000 tree 4c37e44470bd093f9b15f925366c84757828cbb3    debian
  $ git branch -a
  * debian
  $ gbp import-orig --uscan --pristine-tar
  gbp:error:
  Repository does not have branch 'upstream' for upstream sources. If there is none see
  file:///usr/share/doc/git-buildpackage/manual-html/gbp.import.html#GBP.IMPORT.CONVERT
  on howto create it otherwise use --upstream-branch to specify it.

Of course it doesn't, there is none. Let's see.

The first and most obvious issue is that the #-location doesn't exist.
"GBP" doesn't figure once in the HTML.

But finding a "Starting a Debian™ package from scratch" sexion in the
index, I navigated to
  file://localhost/usr/share/doc/git-buildpackage/manual-html/gbp.import.fromscratch.html
which says (these are the entire contents of this document, barring header/footer):
  Starting a Debian™ package from scratch

     So far, we assumed you already have a Debian™ package to start with, but what if you want to start a new package? First, create an empty repository:
    mkdir package-0.1
    cd package-0.1
    git init

     Then, you import the upstream sources, branch off the upstream-branch branch and add the Debian™ files (e.g. via dh_make):
    gbp import-orig -u 0.1 ../package-0.1.tar.gz
    dh_make

     That's it, you're done. If you want to publish your new repository, you can use gbp create-remote-repo.

(a) Why on earth does the directory have a version in it?
(b) gbp import-orig doesn't have an -u option:
      $ man gbp-import-orig | grep -- '-u\b'
      $
    and even if it did, I don't see how it would materially change the error.
(c) I didn't realise, until evaluating this literally phrase-by-phrase,
    what "branch off the upstream-branch branch" was supposed to
    mean, and the entire "Then, you import the upstream sources,
    branch off the upstream-branch branch and add the Debian™ files"
    sequence is incomprehensible:
    (c1) this describes a sequence of
         "import -> create upstream branch -> add debian files";
         import where? this is impossible
    (c2) what in god's name does "branch off the upstream-branch branch" mean
    (c3) what is "the upstream-branch branch". I've never seen a
         branch called "upstream-branch". Why does it spec that
         instead of the documented default of "upstream"?
    (c4) no but really. does it try to mean to spec
           git checkout -b upstream
           git import-orig ...
         or what? Because that's what I did finally after I violated
         (c1) and that worked but. well.
(d) I think this whole thing is worse than just saying
      Repository does not have branch 'upstream' for upstream sources.
      Use --upstream-branch or create it with git checkout -b upstream,
      then gbp import-orig again.
(e) This will also fix the "see [url] on howto create it" salad.

Best,
наб