GIT-UBUNTU(1)

NAME
git-ubuntu - use Git with a Launchpad hosted source package repository

SYNOPSIS
git ubuntu [-h] [-v | --verbose] [--retries <num_retries>] [--retry-backoffs <backoff,...>] [--proto <proto>] [-P | --parentfile <parentfile>] [-L | --pullfile <pullfile>] <command> [<args>]

DESCRIPTION
Ubuntu packages often have changes relative to their Debian bases, referred to as the "Ubuntu delta". git ubuntu represents a collection of tools for dealing with these deltas, implemented as git(1) subcommands.

Part of this work is performed automatically by the "importer", which relies on the Launchpad repository as its source of truth about a given source package's publishing history. The remainder of the work needs to be handled manually, and git ubuntu provides a set of commands (detailed below) for doing so.

A key concept to understand for the git ubuntu workflow is the formalized use of git tags to track version states. These tags will look something like "logical/1%2.3.4.1-1ubuntu3". (Git and debian/changelog conflict on the use of certain reserved characters, such as "~", ":" and ".". These are resolved following the Debian DEP14 version number transformation standard.)

The tag types used by git ubuntu are "logical/", "split/", The first four forms are standardized for git-ubuntu usage and generate tags, respectively, "logical/%(version)s", "split/%(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 <commitish>. The last form allows free-form formatting.

The benefit of using these tools and this formalized tagging system is to simplify future merges from Debian, allowing them to be done as straightforward git rebase operations.

OPTIONS

The following options are common to all git-ubuntu subcommands.

-h, --help
    Prints the synopsis and a list of the most commonly used commands.

-v, --verbose
    Makes git ubuntu verbose. Useful for debugging and seeing what underlying commands are run.

--retries <num_retries>
    Number of retries to attempt for network interactions with Launchpad. The default is 5 retry attempts.

--retry-backoffs <backoff,...>
    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).

--proto <proto>
    Protocol to use when fetching the configured repositories. "git", "http" and "https" are valid options, with "https" the default.

-p <parentfile>, --parentfile <parentfile>
    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. git ubuntu 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:
        <pkgname> <child version> <publish parent version> <changelog parent version>
    with one override per line. A default override file is provided with git ubuntu and end-users generally do not need to provide this option.

-l <pullfile>, --pullfile <pullfile>
    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), git ubuntu needs a mechanism to be told where to obtain accurate sources from. The pullfile specifies this information in the following format:
        <pkgname> <version> <url of dsc file> <urls of orig files>
    with one package per line. "-" for the dsc file indicates to use the one from launchpad. A default override file is provided with git ubuntu and end-users generally do not need to provide this option.

GIT UBUNTU COMMANDS

git-ubuntu-clone(1)
    Clone a repository into a new directory.

git-ubuntu-export-orig(1)
    Export orig tarballs from the Git repository.

git-ubuntu-import(1)
    Import the Launchpad publishing history of a source package into a repository.

git-ubuntu-merge(1)
    Perform an Ubuntu merge.

git-ubuntu-queue(1)
    Interact with the unapproved queue.

git-ubuntu-remote(1)
    Manage tracked repositories.

git-ubuntu-submit(1)
    Submit changes to a repository as a Launchpad Merge Proposal.

git-ubuntu-tag(1)
    Create a tag object, respecting DEP14.

EXIT STATUS
git ubuntu exits with status 0 if a command completes successfully. git ubuntu exits with nonzero exit status on errors.

FILES

$GIT_DIR/.gitconfig, $HOME/.gitconfig
    Some git ubuntu configuration is stored via git config in both the global user and repository local level files. Specificially:
        gitubuntu.lpuser
    Stores the Launchpad user name for authentication in the global user file.

REPORTING BUGS
Report bugs at https://bugs.launchpad.net/git-ubuntu .

AUTHORS
git ubuntu was started conceptually by Robie Basak, and is currently maintained by the Ubuntu Server team. Numerous contributions have been made over the years by those listed in the AUTHORS file.

SEE ALSO
git(1)

https://wiki.ubuntu.com/UbuntuDevelopment/Merging/GitWorkflow

http://www.justgohome.co.uk/blog/2017/07/developing-ubuntu-using-git.html

GIT-UBUNTU
Part of the git-ubuntu(1) suite