Merge ~nacc/git-ubuntu:lp1706798-update-manpages into git-ubuntu:master

[Nish Aravamudan]

Not quite ready yet (still more commands to do), but it can be reviwed in place.

[Nish Aravamudan (nacc)]

Before merging, I'll update the commit message to refer to LP: #1708229.

[Nish Aravamudan (nacc)]

The manpages can be reviewed, still working on the shell completion script.

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

PASSED: Continuous integration, rev:0a7aada5730772c3049625b35771dff103580afd
https://jenkins.ubuntu.com/server/job/git-ubuntu-ci/135/
Executed test runs:
    SUCCESS: Checkout
    SUCCESS: Style Check
    SUCCESS: Unit Tests
    SUCCESS: Integration Tests
    IN_PROGRESS: Declarative: Post Actions

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

review: Approve (continuous-integration)

[Andreas Hasenack (ahasenack)]

Thanks for these manpages, they look great. Most of my comments are just typos, and a few other remarks.

Technically this review is a needs-fixing, but since the changes are super easy, I'll give a +1 ahead of time :)

review: Approve

[Nish Aravamudan (nacc)]

On 03.10.2017 [21:09:50 -0000], Andreas Hasenack wrote:
> Review: Approve
>
> Thanks for these manpages, they look great. Most of my comments are
> just typos, and a few other remarks.

Thank you for the thorough review! I know it's a bit eye-bleeding to
read manpage source!

> Technically this review is a needs-fixing, but since the changes are
> super easy, I'll give a +1 ahead of time :)

Yep, I'll land what I've adjusted based upon your comments in master &
snap/edge and we can iterate from there.

I've elided below anything I updated in the branch.

> > diff --git a/man/man1/git-ubuntu-merge.1 b/man/man1/git-ubuntu-merge.1
> > new file mode 100644
> > index 0000000..01bcc6c
> > --- /dev/null
> > +++ b/man/man1/git-ubuntu-merge.1
> > @@ -0,0 +1,133 @@
> > +.TH "GIT-UBUNTU-MERGE" "1" "2017-07-19" "Git-Ubuntu 0.1" "Git-Ubuntu Manual"
>
> Version should be 0.2
>
> > +
> > +.SH "NAME"
> > +git-ubuntu-merge \- perform an Ubuntu merge of a source package in a Git repository
> > +.SH "SYNOPSIS"
> > +.SP
> > +.NF
> > +\fIgit ubuntu merge\fR [\-\-bug <bug>] [\-\-release <release>]
> > +[\-d | \-\-directory <directory>] [\-f | \-\-force] [\-\-tag-only]
> > +start|finish <commitish> [<onto>]
>
> I think "start|finish" should be "<start|finish>", since either is
> mandatory. If you agree, then the --help output should also get the
> same change.

So this is something I did not change (yet). In my reading around, <>
indicates values of things passed by the end-user. [] indicates
optionality. | indicates a choice. So by not having [] but having | we
are indicating a choice between two required options. Same comment
applies later.

<snip>

> > +Part of the \fBgit-ubuntu\fR(1) suite
> > diff --git a/man/man1/git-ubuntu-queue.1 b/man/man1/git-ubuntu-queue.1
> > new file mode 100644
> > index 0000000..c7badc6
> > --- /dev/null
> > +++ b/man/man1/git-ubuntu-queue.1
> > @@ -0,0 +1,93 @@
> > +.TH "GIT-UBUNTU-QUEUE" "1" "2017-07-19" "Git-Ubuntu 0.2" "Git-Ubuntu Manual"
> > +
> > +.SH "NAME"
> > +git-ubuntu queue \- Interact with the Ubuntu unapproved and new queues in a Git repository
> > +.SH "SYNOPSIS"
> > +.SP
> > +.NF
> > +\fIgit ubuntu queue\fR clean|sync [\-d | \-\-directory <directory>]
>
> I suggest to use <clean|sync> instead of just clean|sync, since both
> are mandatory. If you agree, then the --help output could use the same
> change.

See above.

<snip>

> > diff --git a/man/man1/git-ubuntu-remote.1 b/man/man1/git-ubuntu-remote.1
> > new file mode 100644
> > index 0000000..6ba346c
> > --- /dev/null
> > +++ b/man/man1/git-ubuntu-remote.1
> > @@ -0,0 +1,83 @@
> > +.TH "GIT-UBUNTU-REMOTE" "1" "2017-07-19" "Git-Ubuntu 0.1" "Git-Ubuntu Manual"
>
> Version should be 0.2
>
> > +
> > +.SH "NAME"
> > +git-ubuntu remote \- Manage Launchpad source package Git remotes
> > +.SH "SYNOPSIS"
> > +.SP
> > +.NF
> > +\fIgit ubuntu remote\fR [\-d | \-\-directory <directory>]
> > +[\-l | \-\-lp-user <lp_user>] [\-r | \-\-remote-name <name>]
> > +[\-\-no-fetch] [\-\-package <package>] add <user> [<url>]
> > +.FI
> > +.SP
> > +.SH "DESCRIPTION"
> > +.SP
> > +Launchpad source package repositories are at well-defined locations for
> > +given a username\&.
> > +Thi...

[Nish Aravamudan (nacc)]

review: Approve

diff --git a/doc/gitubuntu-completion.sh b/doc/gitubuntu-completion.sh
index 1c7a8e2..e74fa6e 100644
--- a/doc/gitubuntu-completion.sh
+++ b/doc/gitubuntu-completion.sh
@@ -1,11 +1,16 @@
+SNAP_GIT_BASH_COMPLETION="/snap/git-ubuntu/current/usr/share/bash-completions/completions/git"
+if [ -f $SNAP_GIT_BASH_COMPLETION ]; then
+	. $SNAP_GIT_BASH_COMPLETION
+fi
+
 _git_ubuntu ()
 {
 	local subcommands="
-		import build build-source merge clone tag queue
-		import-local import-ppa remote
+		build build-source clone import import-local import-ppa
+		lint merge queue remote review submit tag
 		"
 	local all_opts="
-		--verbose --parentfile= --pullfile= --help
+		-v --verbose -p --parentfile -l --pullfile -h --help
 		"
 	local net_opts="
 		--retries --retry-backoffs --proto
@@ -30,13 +35,17 @@ _git_ubuntu ()
 			;;
 		build,--*)
 			__gitcomp "
-				--dl-cache --for-merge
+				--dl-cache --sign --for-merge
+				--no-pristine-tar --no-lxd
+				--lxd-profile --keep-build-env --
 				$all_opts $net_opts
 				"
 			;;
 		build-source,--*)
 			__gitcomp "
-				--dl-cache --for-merge --sign
+				--dl-cache --sign --for-merge
+				--no-pristine-tar --no-lxd
+				--lxd-profile --keep-build-env --
 				$all_opts $net_opts
 				"
 			;;
diff --git a/gitubuntu/__main__.py b/gitubuntu/__main__.py
index 78acc15..ffa26ea 100644
--- a/gitubuntu/__main__.py
+++ b/gitubuntu/__main__.py
@@ -72,6 +72,14 @@ def main():
             'review': 'gitubuntu.review',
         }
 
+        help_subcommands = {
+            'build-source',
+            'merge',
+            'clone',
+            'submit',
+            'lint',
+        }
+
         known_network_subcommands = {
             'import',
             'import-local',
@@ -88,12 +96,15 @@ def main():
         parser = argparse.ArgumentParser(
             description='Ubuntu git development tool',
             formatter_class=argparse.RawTextHelpFormatter,
-            epilog='More information is available at https://wiki.ubuntu.com/UbuntuDevelopment/Merging/GitWorkflow.',
+            epilog="For a full description of all subcommands and "
+                   "parameter, see the man-page.\nMore information "
+                   "is available at "
+                   "https://wiki.ubuntu.com/UbuntuDevelopment/Merging/GitWorkflow.",
         )
         subparsers = parser.add_subparsers(
             dest='subcommand',
             help='',
-            metavar='%s' % '|'.join(sorted(known_subcommands)),
+            metavar='%s' % '|'.join(sorted(help_subcommands)),
         )
         # This help ends up not being very useful to the end user
         # subparsers.required = True
@@ -142,14 +153,15 @@ def main():
                 )
             else:
                 help_text = m.parse_args(subparsers, [base_subparser])
-            subparsers.help += '\n'
-            subparsers.help += '\n'.join(
-                textwrap.wrap(
-                    help_text,
-                    subhelp_width,
-                    break_on_hyphens=False,
+            if sub in help_subcommands:
+                subparsers.help += '\n'
+                subparsers.help += '\n'.join(
+                    textwrap.wrap(
+                        help_text,
+                        subhelp_width,
+                        break_on_hyphens=False,
+                    )
                 )
-            )
         parser.add_argument(
             '-P', '--parentfile',
             type=str,
diff --git a/gitubuntu/importppa.py b/gitubuntu/importppa.py
index d5dcb96..3d5ba65 100644
--- a/gitubuntu/importppa.py
+++ b/gitubuntu/importppa.py
@@ -44,11 +44,9 @@ def main(
     ppa,
     pkgname,
     directory,
-    owner,
     user,
     pullfile,
     parentfile,
-    no_clean,
     dl_cache,
     proto,
     retries,
@@ -71,8 +69,6 @@ def main(
         logging.info('Using git repository at %s', repo.local_dir)
     repo.ensure_importer_branches_exist(namespace)
 
-    atexit.register(cleanup, no_clean, repo.local_dir)
-
     source_information = GitUbuntuSourceInformation(
         ppa,
         pkgname,
@@ -199,9 +195,6 @@ def parse_args(subparsers=None, base_subparsers=None):
                         help='Name of PPA to update in the git tree')
     parser.add_argument('package', type=str,
                         help='Which package to update in the git tree')
-    parser.add_argument('-o', '--lp-owner', type=str,
-                        help='Which launchpad user\'s tree to update',
-                        default='usd-import-team')
     parser.add_argument('-l', '--lp-user', type=str,
                         help='Specify the Launchpad user to use',
                         default=getpass.getuser())
@@ -211,11 +204,9 @@ def parse_args(subparsers=None, base_subparsers=None):
                               CACHE_PATH
                              ),
                         default=argparse.SUPPRESS)
-    parser.add_argument('--no-clean', action='store_true',
-                        help='Do not clean the temporary directory')
     parser.add_argument('-d', '--directory', type=str,
                         help='Use git repository at specified location rather '
-                             'than a temporary directory (implies --no-clean). '
+                             'than a temporary directory. '
                              'Will create the local repository if needed.',
                         default=argparse.SUPPRESS
                        )
@@ -229,10 +220,8 @@ def parse_args(subparsers=None, base_subparsers=None):
     return 'import-ppa - %s' % kwargs['description']
 
 def cli_main(args):
-    no_clean = args.no_clean
     try:
         directory = args.directory
-        no_clean = True
     except AttributeError:
         directory = None
     try:
@@ -244,11 +233,9 @@ def cli_main(args):
         args.ppa,
         args.package,
         directory,
-        args.lp_owner,
         args.lp_user,
         args.pullfile,
         args.parentfile,
-        no_clean,
         dl_cache,
         args.proto,
         args.retries,
diff --git a/man/man1/git-ubuntu-build-source.1 b/man/man1/git-ubuntu-build-source.1
new file mode 100644
index 0000000..1b13f31
--- /dev/null
+++ b/man/man1/git-ubuntu-build-source.1
@@ -0,0 +1,101 @@
+.TH "GIT-UBUNTU-BUILD-SOURCE" "1" "2017-07-19" "Git-Ubuntu 0.2" "Git-Ubuntu Manual"
+
+.SH "NAME"
+git-ubuntu build-source \- Build source packages
+.SH "SYNOPSIS"
+.SP
+.NF
+\fIgit ubuntu build-source\fR [\-\-dl-cache <dl_cache>] [\-\-sign]
+[\-\-for-merge] [\-\-no-pristine-tar] [\-\-no-lxd] [\-\-keep-build-env]
+[\-\-lxd-profile <profile>] [-- \&.\&.\&.]
+.FI
+.SP
+.SH "DESCRIPTION"
+.SP
+Build source packages using \fBdpkg-buildpackage\fR(1)\&.
+With --no-lxd and no additional paramaters, this is equivalent to
+calling 'dpkg-buildpackage -S -i -I -us -uc'\&.
+By default, builds will be done in a suitable LXD container\&.
+Any necessary tarballs will be generated by pristine-tar, if possible,
+or downloaded from Launchpad\&.
+.SP
+.SH "OPTIONS"
+.PP
+\-\-dl-cache <dl_cache>
+.RS 4
+The path to use for caching downloads from Launchpad\&.
+By default, downloads are cached inside the repository's GIT_DIR\&.
+.RE
+.PP
+\-\-sign
+.RS 4
+If the build completes successfully, sign the resulting changes file
+with \fBdebsign\fR(1)\&.
+.RE
+.PP
+\-\-for-merge
+.RS 4
+The build will use tarballs from Debian and pass -sa to
+\fBdpkg-buildpackage\fR(1) to include the orig tarball when uploading to
+Ubuntu\&.
+.RE
+.PP
+\-\-no-pristine-tar
+.RS 4
+Do not use pristine-tar when searching for necessary orig tarballs\&.
+This is useful to work around broken imports with missing pristine-tar
+data\&.
+.RE
+.PP
+\-\-no-lxd
+.RS 4
+Do not use LXD when building\&.
+This is dangerous and not recommended for anyone other than experienced
+Ubuntu developers\&.
+If used, it is recommended to pass '-nc -d' as options to
+\fBdpkg-buildpackage\fR(1) (that is, after '--' to this command)\&.
+Otherwise, any required build-dependencies will need to be manually
+installed before building\&.
+.RE
+.PP
+\-\-keep-build-env
+.RS 4
+Keep the build environment (a LXD container or a temporary directory, if
+\-\-no-lxd is passed) after building\&.
+By default, the environment is removed (the container is deleted or the
+directory is removed)\&.
+.RE
+.PP
+\-\-lxd-profile <profile>
+.RS 4
+The LXD profile to use for the build containers\&.
+This might be necessary to support a proxy, for example\&.
+The default LXD profile is used unless this option is specified\&.
+.RE
+.PP
+\-\- \&.\&.\&.
+.RS 4
+Any arguments after '--' are passed on verbatim to
+\fBdpkg-buildpackage\fR(1), after merging them with the default list
+(-S -i -I -us -uc)\&.
+.RE
+.SP
+.SH "EXIT STATUS"
+.SP
+\fIgit ubuntu build\fR exits with status 0 if the build completes
+successfully\&.
+\fIgit ubuntu build\fR exits with nonzero exit status on errors\&.
+.SP
+.SH "REPORTING BUGS"
+.SP
+Report bugs at
+.UR https://bugs.launchpad.net/usd-importer
+.UE
+\.
+.SP
+.SH "SEE ALSO"
+.SP
+\fBgit-ubuntu-build\fR(1), \fBdpkg-buildpackage\fR(1), \fBdebsign\fR(1)
+.SP
+.SH "GIT-UBUNTU"
+Part of the \fBgit-ubuntu\fR(1) suite
diff --git a/man/man1/git-ubuntu-build.1 b/man/man1/git-ubuntu-build.1
new file mode 100644
index 0000000..0a5a6f9
--- /dev/null
+++ b/man/man1/git-ubuntu-build.1
@@ -0,0 +1,98 @@
+.TH "GIT-UBUNTU-BUILD" "1" "2017-07-19" "Git-Ubuntu 0.1" "Git-Ubuntu Manual"
+
+.SH "NAME"
+git-ubuntu build \- Build packages
+.SH "SYNOPSIS"
+.SP
+.NF
+\fIgit ubuntu build\fR [\-\-dl-cache <dl_cache>] [\-\-sign]
+[\-\-for-merge] [\-\-no-pristine-tar] [\-\-no-lxd] [\-\-keep-build-env]
+[\-\-lxd-profile <profile>] [-- \&.\&.\&.]
+.FI
+.SP
+.SH "DESCRIPTION"
+.SP
+Build packages using \fBdpkg-buildpackage\fR(1)\&.
+By default, builds will be done in a suitable LXD container\&.
+Any necessary tarballs will be generated by pristine-tar, if possible,
+or downloaded from Launchpad\&.
+.SP
+.SH "OPTIONS"
+.PP
+\-\-dl-cache <dl_cache>
+.RS 4
+The path to use for caching downloads from Launchpad\&.
+By default, downloads are cached inside the repository's GIT_DIR\&.
+.RE
+.PP
+\-\-sign
+.RS 4
+If the build completes successfully, sign the resulting changes file
+with \fBdebsign\fR(1)\&.
+.RE
+.PP
+\-\-for-merge
+.RS 4
+The build will use tarballs from Debian and pass -sa to
+\fBdpkg-buildpackage\fR(1) to include the orig tarball when uploading to
+Ubuntu\&.
+.RE
+.PP
+\-\-no-pristine-tar
+.RS 4
+Do not use pristine-tar when searching for necessary orig tarballs\&.
+This is useful to work around broken imports with missing pristine-tar
+data\&.
+.RE
+.PP
+\-\-no-lxd
+.RS 4
+Do not use LXD when building\&.
+This is dangerous and not recommended for anyone other than experienced
+Ubuntu developers\&.
+If used, it is recommended to pass '-nc -d' as options to
+\fBdpkg-buildpackage\fR(1) (that is, after '--' to this command)\&.
+Otherwise, any required build-dependencies will need to be manually
+installed before building\&.
+.RE
+.PP
+\-\-keep-build-env
+.RS 4
+Keep the build environment (a LXD container or a temporary directory, if
+\-\-no-lxd is passed) after building\&.
+By default, the environment is removed (the container is deleted or the
+directory is removed)\&.
+.RE
+.PP
+\-\-lxd-profile <profile>
+.RS 4
+The LXD profile to use for the build containers\&.
+This might be necessary to support a proxy, for example\&.
+The default LXD profile is used unless this option is specified\&.
+.RE
+.PP
+\-\- \&.\&.\&.
+.RS 4
+Any arguments after '--' are passed on verbatim to
+\fBdpkg-buildpackage\fR(1)\&.
+.RE
+.SP
+.SH "EXIT STATUS"
+.SP
+\fIgit ubuntu build\fR exits with status 0 if the build completes
+successfully\&.
+\fIgit ubuntu build\fR exits with nonzero exit status on errors\&.
+.SP
+.SH "REPORTING BUGS"
+.SP
+Report bugs at
+.UR https://bugs.launchpad.net/usd-importer
+.UE
+\.
+.SP
+.SH "SEE ALSO"
+.SP
+\fBdpkg-buildpackage\fR(1), \fBdebsign\fR(1)
+.SP
+.SH "GIT-UBUNTU"
+Part of the \fBgit-ubuntu\fR(1) suite
diff --git a/man/man1/git-ubuntu-clone.1 b/man/man1/git-ubuntu-clone.1
new file mode 100644
index 0000000..3db17ef
--- /dev/null
+++ b/man/man1/git-ubuntu-clone.1
@@ -0,0 +1,65 @@
+.TH "GIT-UBUNTU-CLONE" "1" "2017-07-19" "Git-Ubuntu 0.1" "Git-Ubuntu Manual"
+
+.SH "NAME"
+git-ubuntu clone \- Clone a Ubuntu source package repository into a new directory
+.SH "SYNOPSIS"
+.SP
+.NF
+\fIgit ubuntu clone\fR [\-\-lp-user <user>] <package> [<directory>]
+.FI
+.SP
+.SH "DESCRIPTION"
+.SP
+Clones a Ubuntu source package repository given just the source package
+name\&.
+A remote named 'pkg' will be created to track branches from the importer
+repository (See \fBgit-ubuntu-import\fR for details)\&.
+A remote named after the derived Launchpad user will be created for
+tracking their personal branches\&.
+The resulting repository is a regular \fBgit\fR(1) repository and all
+normal \fBgit\fR(1) commands can be used.
+See \fBgit-clone\fR(1) for common operations after cloning\&.
+.SP
+.SH "OPTIONS"
+.PP
+\-\-lp-user <user>
+.RS 4
+The Launchpad user to authenticate as for push URLs as well as
+the default personal remote to create\&.
+If not specified, this value is obtained from 'git config --global
+gitubuntu.lpuser'\&.
+If that config value is not set, a prompt is shown to obtain the
+value\&.
+.RE
+.PP
+<package>
+.RS 4
+The name of the source package to clone\&.
+.RE
+.PP
+<directory>
+.RS 4
+The name of the new directory to clone into\&.
+If not specified, a directory with the same name as \fB<package>\fR is
+used\&.
+.RE
+.SP
+.SH "EXIT STATUS"
+.SP
+\fIgit ubuntu clone\fR exits with status 0 if the build completes
+successfully\&.
+\fIgit ubuntu clone\fR exits with nonzero exit status on errors\&.
+.SP
+.SH "REPORTING BUGS"
+.SP
+Report bugs at
+.UR https://bugs.launchpad.net/usd-importer
+.UE
+\.
+.SP
+.SH "SEE ALSO"
+.SP
+\fBgit-ubuntu\fR(1), \fBgit-clone\fR(1)
+.SP
+.SH "GIT-UBUNTU"
+Part of the \fBgit-ubuntu\fR(1) suite
diff --git a/man/man1/git-ubuntu-import-local.1 b/man/man1/git-ubuntu-import-local.1
new file mode 100644
index 0000000..c046390
--- /dev/null
+++ b/man/man1/git-ubuntu-import-local.1
@@ -0,0 +1,63 @@
+.TH "GIT-UBUNTU-IMPORT-LOCAL" "1" "2017-07-19" "Git-Ubuntu 0.2" "Git-Ubuntu Manual"
+
+.SH "NAME"
+git-ubuntu import-local \- Import a DSC file to Git
+.SH "SYNOPSIS"
+.SP
+.NF
+\fIgit ubuntu import-local\fR [\-d | \-\-directory <directory>]
+<namespace> <dsc>
+.FI
+.SP
+.SH "DESCRIPTION"
+.SP
+Import a Debian source description file (.dsc) to a local Git
+repository\&.
+.SP
+.SH "OPTIONS"
+.PP
+\-d <directory>, \-\-directory <directory>
+.RS 4
+The local directory to perform the import in\&.
+If not specified, use a temporary directory\&.
+.RE
+.PP
+<namespace>
+.RS 4
+The namespace to use for the resultig git-refs after importing the DSC\&
+Unlike publication records from Launchpad, a single DSC file does not
+provide any information to indicate it was actually published to a
+particular distribution\&.
+As a result, no derivation of the namespace is generically possible, and
+we do not want to use the importer/ namespace (as it is reserved for
+\fBgit ubuntu import\fR(1)\&.
+.RE
+.PP
+<dsc>
+.RS 4
+The path to a DSC to import\&.
+This can be either a local filesystem path or a URL to a DSC file\&.
+In the latter case, \fBdget\fR(1) is used to download the file and the
+corresponding source package\&.
+.RE
+.SP
+.SH "EXIT STATUS"
+.SP
+\fIgit ubuntu import-local\fR exits with status 0 if the build completes
+successfully\&.
+\fIgit ubuntu import-local\fR exits with nonzero exit status on
+errors\&.
+.SP
+.SH "REPORTING BUGS"
+.SP
+Report bugs at
+.UR https://bugs.launchpad.net/usd-importer
+.UE
+\.
+.SP
+.SH "SEE ALSO"
+.SP
+\fBgit-ubuntu-import\fR(1)
+.SP
+.SH "GIT-UBUNTU"
+Part of the \fBgit-ubuntu\fR(1) suite
diff --git a/man/man1/git-ubuntu-import-ppa.1 b/man/man1/git-ubuntu-import-ppa.1
new file mode 100644
index 0000000..574df4a
--- /dev/null
+++ b/man/man1/git-ubuntu-import-ppa.1
@@ -0,0 +1,65 @@
+.TH "GIT-UBUNTU-IMPORT-PPA" "1" "2017-07-19" "Git-Ubuntu 0.2" "Git-Ubuntu Manual"
+
+.SH "NAME"
+git-ubuntu import-ppa\- Import a DSC file to Git
+.SH "SYNOPSIS"
+.SP
+.NF
+\fIgit ubuntu import-ppa\fR [\-l | \-\-lp-user <user>]
+[\-d | \-\-directory <directory>] <ppa> <package>
+.FI
+.SP
+.SH "DESCRIPTION"
+.SP
+Import Publishing information from a PPA (Personal Package Archive) to a
+local Git repository\&.
+.SP
+.SH "OPTIONS"
+.PP
+\-l <user>, \-\-lp-user <user>
+.RS 4
+The Launchpad user to authenticate as for push URLs as well as
+the default personal remote to create\&.
+If not specified, this value is obtained from 'git config --global
+gitubuntu.lpuser'\&.
+If that config value is not set, a prompt is shown to obtain the
+value\&.
+.RE
+.PP
+\-d <directory>, \-\-directory <directory>
+.RS 4
+The local directory to perform the import in\&.
+If not specified, use a temporary directory\&.
+.RE
+.PP
+<ppa>
+.RS 4
+The name of the PPA to import from\&.
+Must be specified as "ppa:..."\&.
+.RE
+.PP
+<package>
+.RS 4
+The specific source package's history to import from \fB<ppa>\fR\&.
+.RE
+.SP
+.SH "EXIT STATUS"
+.SP
+\fIgit ubuntu import-ppa\fR exits with status 0 if the build completes
+successfully\&.
+\fIgit ubuntu import-ppa\fR exits with nonzero exit status on
+errors\&.
+.SP
+.SH "REPORTING BUGS"
+.SP
+Report bugs at
+.UR https://bugs.launchpad.net/usd-importer
+.UE
+\.
+.SP
+.SH "SEE ALSO"
+.SP
+\fBgit-ubuntu-import\fR(1)
+.SP
+.SH "GIT-UBUNTU"
+Part of the \fBgit-ubuntu\fR(1) suite
diff --git a/man/man1/git-ubuntu-import.1 b/man/man1/git-ubuntu-import.1
new file mode 100644
index 0000000..92648b0
--- /dev/null
+++ b/man/man1/git-ubuntu-import.1
@@ -0,0 +1,224 @@
+.TH "GIT-UBUNTU-IMPORT" "1" "2017-07-19" "Git-Ubuntu 0.2" "Git-Ubuntu Manual"
+
+.SH "NAME"
+git-ubuntu import \- Import Launchpad publishing history to Git
+.SH "SYNOPSIS"
+.SP
+.NF
+\fIgit ubuntu import\fR [\-o | --lp-owner <owner>] [\-l | \-\-lp-user
+<user>] [\-\-dl-cache <dl_cache>] [\-\-no-fetch] [\-\-no-push]
+[\-\-no-clean] [\-d | \-\-directory <directory>] [\-\-fixup-devel]
+[\-\-active-series-only] [\-\-skip-applied] [\-\-skip-orig]
+[\-\-reimport] <package>
+.FI
+.SP
+.SH "DESCRIPTION"
+.SP
+Import a source package's publication history from Launchpad into a
+local \fBgit\fR(1) repository and push it to a remote repository\&.
+.PP
+The importer algorithm roughly looks like:
+.IP
+.RS 4
+Fetch the \fBowner\fR repository for \fB<package>\fR\&.
+.PP
+For <distribution> in "Debian", "Ubuntu"\&:
+.RS 4
+.PP
+For each <publish> in <distribution> since the most recent
+patches-unapplied import in the local repository\&:
+.RS 4
+.PP
+Import the orig tarballs for <publish> using 'gbp import-orig
+--pristine-tar', unless they have already been imported and the imported
+tarballs are identical.
+.PP
+Find a <publish parent>: the most recent patches-unapplied import to the
+same series and pocket\&.
+.PP
+Find a <changelog parent>: the most recent changelog entry with a
+corresponding patches-unapplied import\&.
+.PP
+Find a <upload parent>: a upload-tag in the repository for the same
+version as <publish> with git-tree-identical contents as <publish>\&.
+.PP
+Commit the git tree corresonding to a patches-unapplied extraction of
+<publish> using all of <publish parent>, <changelog parent> and <upload
+parent> as parents\&.
+.PP
+If this is the first patches-unapplied import of a given version, create
+a tag in refs/tags/import/ pointing to the new commit\&.
+.PP
+Update the patches-applied <distribution>/<publish's series>/<publish's
+pocket> branch to the new commit\&.
+.RE
+.RE
+.RE
+.PP
+.RS 4
+For <distribution> in "Debian", "Ubuntu"\&:
+.PP
+For each <publish> in <distribution> since the most recent
+patches-applied import in the local repository\&:
+.RS 4
+.PP
+Find a <publish parent>: the most recent patches-applied import to the
+same series and pocket\&.
+.PP
+Find a <changelog parent>: the most recent changelog entry with a
+corresponding patches-applied import\&.
+.PP
+Find a <unapplied parent>: the corresponding patches-unapplied import of
+<publish>'s version\&.
+.PP
+Commit each git tree corresponding to the application of the next quilt
+patch in <publish> using all of <publish parent>, <changelog parent> and
+<unapplied parent> as parent\&.
+As each quilt patch is applied, the <unapplied parent> becomes the
+result of the immediately prior patch's application\&.
+.PP
+If this is the first patches-applied import of a given version, create
+a tag in refs/tags/applied/ pointing to the commit corresponding to the
+application of the final quilt patch\&.
+.PP
+Update the patches-applied <distribution>/<publish>'s series/<publish>'s
+pocket branch to the new commit\&.
+.RE
+.RE
+.RE
+.SP
+.SH "OPTIONS"
+.PP
+\-o <owner>, --lp-owner <owner>
+.RS 4
+The Launchpad owner of the remote respository to fetch the current
+repository from and push the resulting import to.
+.RE
+.PP
+\-l <user>, \-\-lp-user <user>
+.RS 4
+The Launchpad user to authenticate as for push URLs as well as
+the default personal remote to create\&.
+If not specified, this value is obtained from 'git config --global
+gitubuntu.lpuser'\&.
+If that config value is not set, a prompt is shown to obtain the
+value\&.
+.RE
+.PP
+\-\-dl-cache <dl_cache>
+.RS 4
+The path to use for caching downloads from Launchpad\&.
+By default, downloads are cached inside the repository's GIT_DIR\&.
+.RE
+.PP
+\-\-no-fetch
+.RS 4
+Do not fetch the \fB<owner>\fR's repository before importing\&.
+Implies --no-push, as the resulting branches are likely to not be
+fast-forwarding.
+.RE
+.PP
+\-\-no-push
+.RS 4
+Do not push the resulting import to the <\fB<owner>\fR's repository
+after importing\&.
+.RE
+.PP
+\-\-no-clean
+.RS 4
+Do not delete local directory used for the import upon completion.
+.RE
+.PP
+\-d <directory>, \-\-directory <directory>
+.RS 4
+The local directory to perform the import in\&.
+Implies --no-clean\&.
+If not specified, use a temporary directory\&.
+.RE
+.PP
+\-\-fixup-devel
+.RS 4
+Always update the ubuntu/<series>-devel branches, even if no imports
+have occurred.
+This option is only intended for \fBgit-ubuntu\fR(1) developers and is
+used to fixup an import when a prior import does not correctly update
+the devel branches\&.
+.RE
+.PP
+\-\-active-series-only
+.RS 4
+Rather than importing all publications from Launchpad, only consider
+those for the currently active series\&.
+This can be useful to just get a quick view of the current state in the
+archive, as a full import can take a very long time\&.
+Implies --no-push\&.
+.RE
+.PP
+\-\-skip-applied
+.RS 4
+Only perform the patches-unapplied portion of the algorithm in
+\fBDESCRIPTION\fR\&.
+This can be useful to just get a quick view of the current state in the
+archive, as a full import can take a very long time\&.
+.RE
+.PP
+\-\-skip-orig
+.RS 4
+Do not attempt to import the orig tarballs\&.
+This can be useful to just get a quick view of the current state in the
+archive, as a full import can take a very long time\&.
+This option can be useful for \fBgit-ubuntu\fR(1) developers when
+debugging issues with 'gbp' or 'pristine-tar'\&.
+.RE
+.PP
+\-\-reimport
+.RS 4
+Reimport the given source package from scratch\&.
+The reimport will still incorporate upload tags as currently present in
+the remote repository\&.
+This option is only intended for \fBgit-ubuntu\fR(1) developers and is
+used when the SHA1s of commits must change due to an implementation
+change in \fIgit ubuntu-import\fR\&.
+A typical reimport of a repository (for safety) will look like:
+.PP
+.RS 4
+git ubuntu import --reimport --no-push --no-clean <package>
+.PP
+This will leave a local directory with the resulting reimport\&.
+The local directory should be examined for the reimport's success; in
+particular, that upload tags are reincorporated in the new history\&.
+.PP
+git ubuntu import --reimport --no-fetch --directory <tempdir from prior
+command>
+.PP
+This will use the local directory, which is current as of the prior
+reimport, ensure it is still current (in case new publishes have
+occurred) and forcibly \fBgit-push\fR the resulting repository to
+\fB<owner>\fR's remote repository.
+.RE
+.RE
+.PP
+<package>
+.RS 4
+The name of the source package to import\&.
+.RE
+.SP
+.SH "EXIT STATUS"
+.SP
+\fIgit ubuntu import\fR exits with status 0 if the build completes
+successfully\&.
+\fIgit ubuntu import\fR exits with nonzero exit status on errors\&.
+.SP
+.SH "REPORTING BUGS"
+.SP
+Report bugs at
+.UR https://bugs.launchpad.net/usd-importer
+.UE
+\.
+.SP
+.SH "SEE ALSO"
+.SP
+\fBquilt\fR(1)
+.SP
+.SH "GIT-UBUNTU"
+Part of the \fBgit-ubuntu\fR(1) suite
diff --git a/man/man1/git-ubuntu-lint.1 b/man/man1/git-ubuntu-lint.1
new file mode 100644
index 0000000..03c61ab
--- /dev/null
+++ b/man/man1/git-ubuntu-lint.1
@@ -0,0 +1,66 @@
+.TH "GIT-UBUNTU-LINT" "1" "2017-07-19" "Git-Ubuntu 0.1" "Git-Ubuntu Manual"
+
+.SH "NAME"
+git-ubuntu-lint \- lint source package changes in a Git repository
+.SH "SYNOPSIS"
+.SP
+.NF
+\fIgit ubuntu lint\fR [\-\-lint-namespace <namespace>]
+[\-\-target-branch <branch>] [\-d | \-\-directory <directory>]
+<commitish>
+.FI
+.SP
+.SH "DESCRIPTION"
+.SP
+\fIgit ubuntu lint\fR performs automated checks on a given Git
+\fBcommitish\fR\&.
+.SP
+.SH "OPTIONS"
+.PP
+\-\-lint-namespace <namespace>
+.RS 4
+The git-reference prefix to search for tags and branches while
+linting\&.
+When linting a remote-tracking branch, the remote name is used as the
+namespace\&.
+When linting a local branch, an empty namespace is used\&.
+This flag provides a manual override and, in general, does not need to
+be specified\&.
+.RE
+.PP
+\-\-target-branch <branch>
+.RS 4
+The target branch which \fBcommitish\fR is based on\&.
+Typically, this is a remote-tracking branch like "pkg/ubuntu/devel"\&.
+If possible, the value is derived\&.
+The most common case when the target branch must be manually specified
+is if two releases contain the same version and it is not possible for
+the linter to determine which specific release the current changes will
+be targetted for\&.
+While the changelog value for the distribution gives a hint, it does not
+tell the linter what the eventual merge will be proposed as\&.
+.RE
+.PP
+\-d <directory>, \-\-directory <directory>
+.RS 4
+The local directory to perform the lint in\&.
+If not specified, the current directory is used\&.
+.RE
+.SP
+.SH "EXIT STATUS"
+.SP
+\fIgit ubuntu lint\fR exits with status 0 if a command completes
+successfully\&.
+\fIgit ubuntu lint\fR exits with nonzero exit status on errors\&.
+.SP
+.SP
+.SH "REPORTING BUGS"
+.SP
+Report bugs at
+.UR https://bugs.launchpad.net/usd-importer
+.UE
+\&.
+.PP
+.SP
+.SH "GIT-UBUNTU"
+Part of the \fBgit-ubuntu\fR(1) suite
diff --git a/man/man1/git-ubuntu-merge.1 b/man/man1/git-ubuntu-merge.1
new file mode 100644
index 0000000..01bcc6c
--- /dev/null
+++ b/man/man1/git-ubuntu-merge.1
@@ -0,0 +1,133 @@
+.TH "GIT-UBUNTU-MERGE" "1" "2017-07-19" "Git-Ubuntu 0.1" "Git-Ubuntu Manual"
+
+.SH "NAME"
+git-ubuntu-merge \- perform an Ubuntu merge of a source package in a Git repository
+.SH "SYNOPSIS"
+.SP
+.NF
+\fIgit ubuntu merge\fR [\-\-bug <bug>] [\-\-release <release>]
+[\-d | \-\-directory <directory>] [\-f | \-\-force] [\-\-tag-only]
+start|finish <commitish> [<onto>]
+wq
+.FI
+.SP
+.SH "DESCRIPTION"
+.SP
+Ubuntu packages often have changes relative to their Debian bases,
+called delta\&.
+\fIgit ubuntu merge\fR assists with performing an Ubuntu merge, by
+replaying the Ubuntu delta on a newer version from Debian as a
+\fBgit-rebase\fR(1)\&.
+Once an Ubuntu merge has been performed using this workflow, future
+merges can be simple rebases\&.
+In the most general case, an Ubuntu merge is begun with `git ubuntu
+merge start pkg/ubuntu/devel pkg/debian/sid` and finished with `git
+ubuntu merge finish pkg/ubuntu/devel pkg/debian/sid`\&.
+.PP
+The brief outline of the merge workflow supported by \fBgit ubuntu merge\fR
+is:
+.IP
+.RS 4
+Obtain git tree with \fBgit ubuntu clone\fR(1)\&.
+.PP
+Deconstruct the current Ubuntu delta into a sequence of logical
+commits suitable for rebasing\&.
+.PP
+Rebase the logical Ubuntu delta onto the new Debian version\&.
+.PP
+Build and test the resulting source package with \fBgit ubuntu
+build\fR(1) and \fBautopkgtest\fR(1)\&.
+.PP
+Reconstruct the debian/changelog for the new source package\&.
+.PP
+Update the metadata for the new source package, such as the
+maintainer\&.
+.PP
+Upload the resulting source package to the Ubuntu archive\&.
+.RE
+.RE
+.PP
+A more extensive discussio of the workflow is at
+.UR https://wiki.ubuntu.com/UbuntuDevelopment/Merging/GitWorkflow#Detailed_workflow
+.UE
+.SP
+.SH "OPTIONS"
+.PP
+start | finish
+.RS 4
+The step of the merge\&.
+When "start" is specified, the current delta will be reconstructed and
+HEAD will point to the result\&.
+When "finish" is specified, the debian/changelog will be reconstructed
+and package metadata will be updated\&.
+"start" must be run before "finish"\&.
+.RE
+.PP
+\-\-bug <bug>
+.RS 4
+When passed to the \fBstart\fR step, the tags created will be under
+lp\fB<bug>\fR/ in the repository\&.
+When passed to the \fBfinish\fR step, the Lauchpad bug \fB<bug>\fR will
+be closed by the resulting debian/changelog\&.
+.RE
+.PP
+\-\-release <release>
+.RS 4
+The \fB<release>\fR to use in the final changelog\&.
+If not specified, the current development release is assumed\&.
+.RE
+.PP
+\-d <directory>, \-\-directory <directory>
+.RS 4
+The local directory to perform the merge in\&.
+If not specified, the current directory is used\&.
+.RE
+.PP
+\-f | \-\-force
+.RS 4
+Overwrite any tags, if they already exist\&.
+.RE
+.PP
+\-\-tag-only
+.RS 4
+In some cases, the full workflow is not desired\&.
+When this flag is set, only the tags for "old/ubuntu", "old/debian" and
+"new/debian" are created\&.
+.RE
+.PP
+<commitish>
+.RS 4
+A Git commitish indicating the current Ubuntu changes to merge to
+Debian\&.
+.RE
+.PP
+.RS 4
+[<onto>]
+.RE
+A Git commitish indicating the new Debian version to merge to\&.
+If not specified, "debian/sid" is assumed.
+If a local branch with name \fB<onto>\fR does not exist, it will be
+start from the remote-tracking branch "pkg/\fB<onto>\fR"\&.
+.SP
+.SH "EXIT STATUS"
+.SP
+\fIgit ubuntu merge\fR exits with status 0 if a command completes
+successfully\&.
+\fIgit ubuntu merge\fR exits with nonzero exit status on errors\&.
+.SP
+.SP
+.SH "REPORTING BUGS"
+.SP
+Report bugs at
+.UR https://bugs.launchpad.net/usd-importer
+.UE
+\&.
+.PP
+.SP
+.SH "SEE ALSO"
+.SP
+\fBgit-rebase\fR(1), \fBgit-ubuntu-clone\fR(1),
+\fBgit-ubuntu-build\fR(1), \fBautopkgtest\fR(1)
+.SP
+.SH "GIT-UBUNTU"
+Part of the \fBgit-ubuntu\fR(1) suite
diff --git a/man/man1/git-ubuntu-queue.1 b/man/man1/git-ubuntu-queue.1
new file mode 100644
index 0000000..c7badc6
--- /dev/null
+++ b/man/man1/git-ubuntu-queue.1
@@ -0,0 +1,93 @@
+.TH "GIT-UBUNTU-QUEUE" "1" "2017-07-19" "Git-Ubuntu 0.2" "Git-Ubuntu Manual"
+
+.SH "NAME"
+git-ubuntu queue \- Interact with the Ubuntu unapproved and new queues in a Git repository
+.SH "SYNOPSIS"
+.SP
+.NF
+\fIgit ubuntu queue\fR clean|sync [\-d | \-\-directory <directory>]
+.PP
+\fIgit ubuntu queue\fR sync [\-\-source <source>]
+[\-\-series <series>] [\-\-parent <parent>] [\-\-orphan]
+[\-\-no-trim] [\-\-new] [\-\-unapproved] [\-\-no-fetch]
+.FI
+.SP
+.SH "DESCRIPTION"
+.SP
+Import unapproved and new uploads for Ubuntu source packages to the
+local repository\&.
+.SP
+.SH "OPTIONS"
+.PP
+clean|sync
+.RS 4
+The mode to operate in.
+If "clean", delete all local queue-related tags\&.
+If "sync", import uploads to the unapproved and new queues\&.
+.RE
+.PP
+Both "clean" and "sync" recognize:
+.PP
+\-d <directory>, \-\-directory <directory>
+.RS 4
+The local directory to perform the merge in\&.
+If not specified, the current directory is used\&.
+.RE
+.PP
+"sync" also recognizes:
+.PP
+\-\-source <source>
+.RS 4
+Override source package name on which to act\&.
+.RE
+.PP
+\-\-series <series>
+.RS 4
+Override Ubuntu series on which to act\&.
+.RE
+.PP
+\-\-parent <parent>
+.RS 4
+Override commit parent for new imports\&.
+.RE
+.PP
+\-\-orphan
+.RS 4
+Force new imports to be orphan commits\&.
+.RE
+.PP
+\-\-no-trim
+.RS 4
+Do not remove old tags\&.
+.RE
+.PP
+\-\-new
+.RS 4
+Only consider the New queue\&.
+.RE
+.PP
+\-\-unapproved
+.RS 4
+Only consider the Unapproved queue\&.
+.RE
+.PP
+\-\-no-fetch
+.RS 4
+Do not fetch from the importer repository first\&.
+.RE
+.SP
+.SH "EXIT STATUS"
+.SP
+\fIgit ubuntu queue\fR exits with status 0 if the build completes
+successfully\&.
+\fIgit ubuntu queue\fR exits with nonzero exit status on errors\&.
+.SP
+.SH "REPORTING BUGS"
+.SP
+Report bugs at
+.UR https://bugs.launchpad.net/usd-importer
+.UE
+\.
+.SP
+.SH "GIT-UBUNTU"
+Part of the \fBgit-ubuntu\fR(1) suite
diff --git a/man/man1/git-ubuntu-remote.1 b/man/man1/git-ubuntu-remote.1
new file mode 100644
index 0000000..6ba346c
--- /dev/null
+++ b/man/man1/git-ubuntu-remote.1
@@ -0,0 +1,83 @@
+.TH "GIT-UBUNTU-REMOTE" "1" "2017-07-19" "Git-Ubuntu 0.1" "Git-Ubuntu Manual"
+
+.SH "NAME"
+git-ubuntu remote \- Manage Launchpad source package Git remotes
+.SH "SYNOPSIS"
+.SP
+.NF
+\fIgit ubuntu remote\fR [\-d | \-\-directory <directory>]
+[\-l | \-\-lp-user <lp_user>] [\-r | \-\-remote-name <name>]
+[\-\-no-fetch] [\-\-package <package>] add <user> [<url>]
+.FI
+.SP
+.SH "DESCRIPTION"
+.SP
+Launchpad source package repositories are at well-defined locations for
+given a username\&.
+This subcommand allows users to add these well-defined locations to a
+local \fBgit\fR(1) repository\&.
+Once added, the remote can be manipulated like any Git remote\&.
+.SP
+.SH "OPTIONS"
+.PP
+\-d <directory>, \-\-directory <directory>
+.RS 4
+The local directory to manage the remote in\&.
+If not specified, the current directory is used\&.
+.RE
+.PP
+\-l <lp_user>, \-\-lp-user <lp_user>
+.RS 4
+The Launchpad user to authenticate as for push URLs\&.
+.RE
+.PP
+\-r, \-\-remote-name <name>
+.RS 4
+The remote name to use\&.
+If not specified, the remote will be named "\fB<user>\fR"\&.
+.RE
+.PP
+\-\-no-fetch
+.RS 4
+Do not fetch the remote after adding it\&.
+.RE
+.PP
+\-\-package <package>
+.RS 4
+The source package, and thus the repository, to download from
+this user\&.
+By default, the source package is derived from the current directory's
+debian/changelog\&.
+.RE
+.PP
+<user>
+.RS 4
+The Launchpad username that owns the repository to add\&.
+.RE
+.PP
+<url>
+.RS 4
+The URL to add as a remote\&.
+If the auto-derived URL from \fB<user>\fR and the debian/changelog's
+source package is not desired, it can be manually specified\&.
+.RE
+.SP
+.SH "EXIT STATUS"
+.SP
+\fIgit ubuntu remote\fR exits with status 0 if the build completes
+successfully\&.
+\fIgit ubuntu remote\fR exits with nonzero exit status on errors\&.
+.SP
+.SH "REPORTING BUGS"
+.SP
+Report bugs at
+.UR https://bugs.launchpad.net/usd-importer
+.UE
+\.
+.SP
+.SH "SEE ALSO"
+.SP
+\fBgit-remote\fR(1)
+.SP
+.SH "GIT-UBUNTU"
+Part of the \fBgit-ubuntu\fR(1) suite
diff --git a/man/man1/git-ubuntu-review.1 b/man/man1/git-ubuntu-review.1
new file mode 100644
index 0000000..3afc804
--- /dev/null
+++ b/man/man1/git-ubuntu-review.1
@@ -0,0 +1,56 @@
+.TH "GIT-UBUNTU-REVIEW" "1" "2017-07-19" "Git-Ubuntu 0.1" "Git-Ubuntu Manual"
+
+.SH "NAME"
+git-ubuntu review \- Review Launchpad merge proposals for source packages
+.SH "SYNOPSIS"
+.SP
+.NF
+\fIgit ubuntu review\fR [\-\-clone] [\-\-add-comment] <url>
+.FI
+.SP
+.SH "DESCRIPTION"
+.SP
+This command is similar to \fBgit-ubuntu-lint\fR(1) except that it works
+"remotely" in order to review Merge Proposals (MPs) on Launchpad\&.
+Currently \fBgit ubuntu review\fR simply ensures the source and target
+branches of the MP are available in the local repository and performs a
+lint of the proposed changes\&.
+.SP
+.SH "OPTIONS"
+.PP
+\-\-clone
+.RS 4
+Create a new local repository using \fBgit-ubuntu-clone\fR(1)\&.
+By default, the repository at the current directory is used\&.
+.RE
+.PP
+\-\-add-comment
+.RS 4
+Add a comment to the Merge Proposal at \fB<url>\fR with the results of
+the \fBgit-ubuntu-lint\fR(1) invocation\&.
+.RE
+.PP
+<url>
+.RS 4
+The URL of a Merge Proposal to review\&.
+.RE
+.SP
+.SH "EXIT STATUS"
+.SP
+\fIgit ubuntu review\fR exits with status 0 if the build completes
+successfully\&.
+\fIgit ubuntu review\fR exits with nonzero exit status on errors\&.
+.SP
+.SH "REPORTING BUGS"
+.SP
+Report bugs at
+.UR https://bugs.launchpad.net/usd-importer
+.UE
+\.
+.SP
+.SH "SEE ALSO"
+.SP
+\fBgit-ubuntu-lint\fR(1), \fBgit-ubuntu-submit\fR(1)
+.SP
+.SH "GIT-UBUNTU"
+Part of the \fBgit-ubuntu\fR(1) suite
diff --git a/man/man1/git-ubuntu-submit.1 b/man/man1/git-ubuntu-submit.1
new file mode 100644
index 0000000..70fbe19
--- /dev/null
+++ b/man/man1/git-ubuntu-submit.1
@@ -0,0 +1,94 @@
+.TH "GIT-UBUNTU-SUBMIT" "1" "2017-07-19" "Git-Ubuntu 0.1" "Git-Ubuntu Manual"
+
+.SH "NAME"
+git-ubuntu submit \- Submit local changes as a Launchpad merge proposal
+.SH "SYNOPSIS"
+.SP
+.NF
+\fIgit ubuntu submit\fR [\-\-target-branch <target_branch>]
+[\-\-reviewer <reviewer>] [\-d | \-\-directory <directory>]
+[\-f | \-\-force] [\-\-target-user <user>] [\-\-branch <branch>]
+[\-\-no-push] [\-l | \-\-lp-user <lp_user>]
+.FI
+.SP
+.SH "DESCRIPTION"
+.SP
+This command and \fBgit-ubuntu-review\fR(1) are in some ways
+symmetrical\&.
+"submit" proposes local changes for external review and "review" reviews
+them\&.
+In many ways, this is meant to mirror the GitHub model for Pull
+Requests\&.
+.SP
+.SH "OPTIONS"
+.PP
+\-\-target-branch <target_branch>
+.RS 4
+The branch in \fB<user>\fR's repository to target\&.
+If not specified, the nearest remote-tracking branch to \fB<branch>\fR
+is used\&.
+.RE
+.PP
+\-\-reviewer <reviewer>
+.RS 4
+The reviewer on Launchpad for the Merge Proposal, specified by the
+Launchpad user (or team) name\&.
+This option can be specified multiple times\&.
+If not specified, the canonical-server team is used\&.
+.RE
+.PP
+\-d <directory>, \-\-directory <directory>
+.RS 4
+The local directory to submit from\&.
+If not specified, the current directory is used\&.
+.RE
+.PP
+\-f, \-\-force
+.RS 4
+Overwrite any existing tags or branches, as necessary\&.
+.RE
+.PP
+\-\-target-user <user>
+.RS 4
+The Launchpad user (or team) name owning the repository to propose the
+local changes into\&.
+By default this is the "usd-import-team" Launchpad team, which owns the
+imported repositories\&.
+.RE
+.PP
+\-\-branch <branch>
+.RS 4
+What local branch to submit for merging into \fB<user>\fR's
+\fB<target_branch>\fR\&.
+If not specified, the branch pointed to by HEAD is used\&.
+.RE
+.PP
+\-\-no-push
+.RS 4
+Do not push the \fB<branch>\fR before creating the Merge Proposal\&.
+.RE
+.PP
+\-l <lp_user>, \-\-lp-user <lp_user>
+.RS 4
+The Launchpad user to authenticate as for pushing changes\&.
+.RE
+.SP
+.SH "EXIT STATUS"
+.SP
+\fIgit ubuntu submit\fR exits with status 0 if the build completes
+successfully\&.
+\fIgit ubuntu submit\fR exits with nonzero exit status on errors\&.
+.SP
+.SH "REPORTING BUGS"
+.SP
+Report bugs at
+.UR https://bugs.launchpad.net/usd-importer
+.UE
+\.
+.SP
+.SH "SEE ALSO"
+.SP
+\fBgit-ubuntu-review\fR(1)
+.SP
+.SH "GIT-UBUNTU"
+Part of the \fBgit-ubuntu\fR(1) suite
diff --git a/man/man1/git-ubuntu-tag.1 b/man/man1/git-ubuntu-tag.1
new file mode 100644
index 0000000..4eb9c12
--- /dev/null
+++ b/man/man1/git-ubuntu-tag.1
@@ -0,0 +1,85 @@
+.TH "GIT-UBUNTU-TAG" "1" "2017-07-19" "Git-Ubuntu 0.1" "Git-Ubuntu Manual"
+
+.SH "NAME"
+git-ubuntu tag \- Create Git tags respecting DEP14 and debian/changelog
+.SH "SYNOPSIS"
+.SP
+.NF
+\fIgit ubuntu tag\fR [\-\-logical | \-\-deconstruct | \-\-reconstruct |
+\-\-upload | \-\-format <format>] [\-\-bug <bug>]
+[\-d | \-\-directory <directory>] [\-f | \-\-force]
+[\-\-print-name-only] [<commitish>]
+.FI
+.SP
+.SH "DESCRIPTION"
+.SP
+\fBgit-ubuntu-merge\fR(1) and potentially other commands expect to use
+and resolve specific tags including source package versions\&.
+However, debian/changelog and Git conflict on the use of certain
+reserved characters, such as '~', ':' and '.'\&.
+To resolve this, Debian has a standard DEP14
+.UR http://dep.debian.net/deps/dep14/
+.UE
+which covers the appropriate transformations for versions\&.
+\fBgit-ubuntu\fR follows this convention for "version mangling" but not
+necessarily any others\&.
+.SP
+.SH "OPTIONS"
+.PP
+\-\-logical, \-\-deconstruct, \-\-reconstruct, \-\-upload, \-\-format <format>
+.RS 4
+Specify a format for the created tag\&.
+The first four forms are standardized for \fBgit-ubuntu\fR usage and
+generate tags, respectively, "logical/%(version)s",
+"deconstruct/%(version)s", "reconstruct/%(version)s",
+"upload/%(versions)s", where "%(versions)" will be replaced by the DEP14
+mangling of the last version in debian/changelog as present in
+\fB<commitish>\fR\&.
+The last form allows free-form formatting\&.
+If none of these options are given, an upload tag will be created\&.
+.RE
+.PP
+\-\-bug <bug>
+.RS 4
+Launchpad bug to use to namespace the tags\&.
+If specified, this will prefix the tag with "lp\fB<bug>\fR/"\&.
+.RE
+.PP
+\-d <directory>, \-\-directory <directory>
+.RS 4
+The local directory to tag in\&.
+If not specified, the current directory is used\&.
+.RE
+.PP
+\-f, \-\-force
+.RS 4
+Overwrite existing tags, if necessary\&.
+.RE
+.PP
+\-\-print-name-only
+.RS 4
+Only print the name of the specified tag, but do not create\&.
+This can be useful for use by other scripts\&.
+.RE
+.PP
+[<commitish>]
+.RS 4
+The commitish in the repository to tag\&.
+If not specified, HEAD is tagged\&.
+.RE
+.SP
+.SH "EXIT STATUS"
+.SP
+\fIgit ubuntu tag\fR exits with status 0 if the build completes
+successfully\&.
+\fIgit ubuntu tag\fR exits with nonzero exit status on errors\&.
+.SP
+.SH "REPORTING BUGS"
+.SP
+Report bugs at
+.UR https://bugs.launchpad.net/usd-importer
+.UE
+\.
+.SP
+.SH "GIT-UBUNTU"
+Part of the \fBgit-ubuntu\fR(1) suite
diff --git a/man/man1/git-ubuntu.1 b/man/man1/git-ubuntu.1
index e0a6a12..3c61762 100644
--- a/man/man1/git-ubuntu.1
+++ b/man/man1/git-ubuntu.1
@@ -1,139 +1,214 @@
-.TH "GIT-UBUNTU" "1" "2017-05-22" "Git-Ubuntu 1.0" "Git-Ubuntu Manual"
+.TH "GIT-UBUNTU" "1" "2017-07-19" "Git-Ubuntu 0.1" "Git-Ubuntu Manual"
 
 .SH "NAME"
-git-ubuntu \- use git with a Launchpad hosted source package repository
+git-ubuntu \- use Git with a Launchpad hosted source package repository
 .SH "SYNOPSIS"
-.sp
-.nf
-\fIgit ubuntu\fR [\-h] [\-P PARENTFILE] [\-L PULLFILE] <command> [<args>]
-.fi
-.sp
+.SP
+.NF
+\fIgit ubuntu\fR [\-h] [\v | \-\-verbose] [\-\-retries <num_retries>]
+[\-\-retry-backoffs <backoff,\&.\&.\&.>] [\-\-proto <proto>]
+[\-P | \-\-parentfile <parentfile>] [\-L | \-\-pullfile <pullfile>]
+<command> [<args>]
+.FI
+.SP
 .SH "DESCRIPTION"
-.sp
-\fIgit ubuntu\fR is a wrapper for interacting with a source package
-repository on Launchpad. \fIgit ubuntu\fR only 'trusts' the Publishing
-History of a source package as presented by Launchpad to provide
-source package information.
-.sp
+.SP
+\fIgit ubuntu\fR is a \fBgit\fR(1) subcommand for interacting with a
+source package repository on Launchpad\&.
+\fIgit ubuntu\fR only 'trusts' the Publishing History of a source
+package as presented by Launchpad to provide source package
+information\&.
+.SP
 Once tracking a Launchpad repository, the Git repository can be
-updated with normal \fIgit\fR commands. For Ubuntu developers,
-commands (detailed below) exist for performing Ubuntu merges, building
-source packages and dealing with the unapproved queue.
-.sp
-.SH "COMMANDS"
+updated with normal \fIgit\fR commands\&.
+For Ubuntu developers, commands (detailed below) exist for performing
+Ubuntu merges, building source packages and dealing with the unapproved
+queue\&.
+.SP
+.SH "OPTIONS"
 .PP
-\fIbuild\fR
-\fIbuild-source\fR
+\-h, \-\-help
 .RS 4
+Prints the synopsis and a list of the most commonly used commands\&.
 .RE
 .PP
-\fIclone\fR
+\-v, \-\-verbose
 .RS 4
+Makes \fIgit ubuntu\fR verbose\&.
+Useful for debugging and seeing what underlying commands are run\&.
 .RE
 .PP
-\fIimport\fR
+\-\-retries <num_retries>
 .RS 4
+Number of retries to attempt for network interactions with Launchpad\&.
+Periodically, Launchpad may not respond for approximately 10 minutes,
+and clients simply need to retry until success\&.
+The default is 3 retry attempts\&.
 .RE
 .PP
-\fIimport-local\fR
+\-\-retry-backoffs <backoff,\&.\&.\&.>
 .RS 4
+Comma-separated list of backoff durations (in seconds) to use between
+retry attempts\&.
+The default is exponential backoff (with the default --retries value,
+this corresponds to 1, 2 and 4 seconds between subsequent retry
+attempts)\&.
 .RE
 .PP
-\fIimport-ppa\fR
+\-\-proto <proto>
 .RS 4
+Protocol to use when fetching the configured repositories\&.
+'git', 'http' and 'https' are valid options, with 'https' the default\&.
 .RE
 .PP
-\fImerge\fR
+\-p <parentfile>, \-\-parentfile <parentfile>
+.RS 4
+Path to a parent overrides file\&.
+The import algorithm cannot always correctly determine the parenting
+relationship between source package publications, particularly for
+older historical publications\&.
+\fIgit ubuntu\fR needs a mechanism to be told what the parents of a
+publication are when they cannot be correctly deduced\&. The parentfile
+specifies this information in the following format:
 .RS 4
+<pkgname> <child version> <publish parent version> <changelog parent version>
+.RE
+with one override per line\&. 
+.SP
+A default override file is provided with \fIgit ubuntu\fR and
+end-users generally do not need to provide this option\&.
 .RE
 .PP
-\fIqueue\fR
+\-l <pullfile>, \-\-pullfile <pullfile>
+.RS 4
+Path to a pull overrides file\&.
+If the Launchpad source package data is inaccurate
+for a publish (this happens, for example, when a same-versioned source
+package is published multiple times with different orig tarballs),
+\fIgit ubuntu\fR needs a mechanism to be told where to obtain accurate
+sources from\&.
+The pullfile specifies this information in the following format:
 .RS 4
+<pkgname> <version> <url of dsc file> <urls of orig files>
+.RE
+with one package per line\&. '\-' for the dsc file indicates to use the
+one from launchpad\&.
+.SP
+A default override file is provided with \fIgit ubuntu\fR and
+end-users generally do not need to provide this option\&.
 .RE
+.SP
+.SH "GIT UBUNTU COMMANDS"
 .PP
-\fIremote\fR
+\fBgit-ubuntu-build\fR(1)
+\fBgit-ubuntu-build-source\fR(1)
 .RS 4
+Build binary and source packages\&.
 .RE
 .PP
-\fItag\fR
+\fBgit-ubuntu-clone\fR(1)
 .RS 4
+Clone a repository into a new directory\&.
 .RE
-.SH "OPTIONS"
 .PP
-\-h, \-\-help
+\fBgit-ubuntu-import\fR(1)
 .RS 4
-Prints the synopsis and a list of the most commonly used commands.
+Import the Launchpad publishing history of a source package into a
+repository\&.
 .RE
 .PP
-\-P PARENTFILE, \-\-parentfile PARENTFILE
+\fBgit-ubuntu-import-local\fR(1)
 .RS 4
-The import algorithm cannot always correctly determine the parenting
-relationship between source package publications, particularly for
-older historical publications. \fIgit ubuntu\fR needs a mechanism
-to be told what the parents of a publication are when they cannot be
-correctly deduced. the PARENTFILE specifies this information in the
-following format:
+Import a DSC file into a repository\&.
+.RE
+.PP
+\fBgit-ubuntu-import-ppa\fR(1)
 .RS 4
-<pkgname> <child version> <publish parent version> <changelog parent version>
+Import the publishing history of a PPA into a repository\&.
 .RE
-with one override per line. 
-.sp
-A default override file is provided with \fIgit ubuntu\fR and
-end-users generally do not need to provide this option.
+.PP
+\fBgit-ubuntu-lint\fR(1)
+.RS 4
+Perform static checking on changes in a repository\&.
 .RE
 .PP
-\-L PULLFILE, \-\-pullfile PULLFILE
+\fBgit-ubuntu-merge\fR(1)
 .RS 4
-If, for any reason, the Launchpad source package data is inaccurate
-for a publish (this happens, e.g., when a same-versioned source
-package is published multiple times with different orig tarballs),
-\fIgit ubuntu\fR needs a mechanism to be told where to obtain accurate
-sources from. The PULLFILE specifies this information in the following
-format:
+Perform an Ubuntu merge\&.
+.RE
+.PP
+\fBgit-ubuntu-queue\fR(1)
 .RS 4
-<pkgname> <version> <URL of DSC file> <URLs of orig files>
+Interact with the unapproved queue\&.
 .RE
-with one package per line. '\-' for the DSC file indicates to use the
-one from Launchpad.
-.sp
-A default override file is provided with \fIgit ubuntu\fR and
-end-users generally do not need to provide this option.
+.PP
+\fBgit-ubuntu-remote\fR(1)
+.RS 4
+Manage tracked repositories\&.
+.RE
+.PP
+\fBgit-ubuntu-review\fR(1)
+.RS 4
+Perform a review of a Launchpad Merge Proposal\&.
+.RE
+.PP
+\fBgit-ubuntu-submit\fR(1)
+.RS 4
+Submit changes to a repository as a Launchpad Merge Proposal\&.
 .RE
-.sp
-.SH "EXIT VALUE"
-.sp
+.PP
+\fBgit-ubuntu-tag\fR(1)
+.RS 4
+Create a tag object, respecting DEP14\&.
+.RE
+.SP
+.SH "EXIT STATUS"
+.SP
 \fIgit ubuntu\fR exits with status 0 if a command completes
-successfully. \fIgit ubuntu\fR exits with nonzero exit status on
-errors.
-.sp
+successfully\&.
+\fIgit ubuntu\fR exits with nonzero exit status on errors\&.
+.SP
 .SH "FILES"
 .PP
-$GIT_DIR/.gitconfig, $HOME/.gitconfig
+$GIT_DIR/\&.gitconfig, $HOME/\&.gitconfig
 .RS 4
 Some \fIgit ubuntu\fR configuration is stored via \fIgit config\fR in
-both the global user and repository local level files. Specificially:
-.sp
-gitubuntu.lpuser
+both the global user and repository local level files\&.
+Specificially:
+.SP
 .RS 4
-Stores the Launchpad user name for authentication in the global user
-file.
+gitubuntu\&.lpuser
 .RE
+Stores the Launchpad user name for authentication in the global user
+file\&.
 .RE
-.sp
+.SP
 .SH "REPORTING BUGS"
-.sp
-Report bugs at .UR https://bugs.launchpad.net/usd-importer .UE.
+.SP
+Report bugs at
+.UR https://bugs.launchpad.net/usd-importer
+.UE
+\&.
+.PP
 .SH "AUTHORS"
-.sp
+.SP
 \fIgit ubuntu\fR was started conceptually by Robie Basak, and is
-currently maintained by Nishanth Aravamudan. Numerous contributions
-have been made by Scott Moser and other members of the Ubuntu Server
-team.
-.sp
+currently maintained by Nishanth Aravamudan\&.
+Numerous contributions have been made by Scott Moser and other members
+of the Ubuntu Server team\&.
+.SP
 .SH "SEE ALSO"
-.sp
+.SP
 \fBgit\fR(1)
-.sp
-.UR
-https://wiki.ubuntu.com/UbuntuDevelopment/Merging/GitWorkflow
+.PP
+.UR https://wiki\&.ubuntu\&.com/UbuntuDevelopment/Merging/GitWorkflow
 .UE
+.PP
+.\" Would prefer to use the following URL, but it is static
+.\" .UR https://insights\&.ubuntu\&.com/2017/07/24/developing-ubuntu-using-git/
+.\" .UE
+.UR http://www\&.justgohome\&.co\&.uk/blog/2017/07/developing-ubuntu-using-git\&.html
+.UE
+.PP
+.SH "GIT-UBUNTU"
+Part of the \fBgit-ubuntu\fR(1) suite