Repositories

Repositories
Prev		Next

We use Git repositories, hosted by Debian. You can have a look at the repositories through the web interface.

The Git repository is the primary location for our source packages these days.

Give me the source!

To check the sources of a package (referred as <package> below) in our repositories, use the debcheckout command, from the devscripts package.

If the package is already in the archive:
```
debcheckout --git-track '*' <package>
```

For draft packages that are only on Salsa:

debcheckout --git-track '*' https://salsa.debian.org/debian-gis-team/<package>.git

You can configure Git to use SSH only for push actions, by changing the URL:

git remote set-url --push origin git@salsa.debian.org:debian-gis-team/<package>.git

SSH tips

You can avoid typing your SSH password again and again using the ssh-add command. On remote connections the SSH agent needs to be enabled with the command eval $(ssh-agent).

Git repository

Common Git branches
Other Git branches
Tags for upstream and package releases
Upstream Git repositories

The namespace on Salsa that contains the Git repositories (debian-gis-team) uses as flat hierarchy for packages and related Debian GIS repositories.

There is no mandated layout for the package repositories, the following layout is recommended though.

debian-gis-team/
 ├ <package-A>.git
 │  ├ master
 │  │  ├ <upstream sources>
 │  │  └ debian/
 │  ├ pristine-tar
 │  └ upstream
 ├ <package-B>.git
 │  ├ master
 │  │  ├ <upstream sources>
 │  │  └ debian/
 │  ├ wheezy
 │  │  ├ <upstream sources>
 │  │  └ debian/
 │  ├ ubuntugis/quantal
 │  │  ├ <upstream sources>
 │  │  └ debian/
 │  ├ pristine-tar
 │  └ upstream
 ┆
 └ debian-gis-team.pages.debian.net.git
    └ master

Common Git branches

Most of our packages using Git are managed following the standard layout of the git-buildpackage helper.

The master branch contains the full source package.
Upstream sources are merged with Debian-specific changes in the master branch, which is the usual place to work in.
The pristine-tar branch contains the data necessary to recreate an original tarball from the repository with a reproducible checksum.
The data needed to regenerate original source tarballs from the upstream branch are kept with the help of the pristine-tar tool in the pristine-tar branch.
The upstream branch contains the upstream source, after repacking when necessary (non-free files, large convenience code copies, …).
Upstream sources are kept (in plain, uncompressed form) in the upstream branch.

Other Git branches

Changes uploaded to other distributions than Debian unstable can be stored in other branches, named for instance experimental, bookworm, etc.

This is useful in case updates to packages in Debian stable are made and the master branch already uses a newer upstream release. Using dedicated branches for the older version in Debian named after the release codename is recommended.

Packaging for the UbuntuGIS PPA is encouraged to be stored in Ubuntu release specific branches such as ubuntugis/trusty, ubuntugis/xenial, etc.

Likewise packaging for other derivatives can be maintained in the Debian GIS git repository in derivative specific branches. OSGeo-Live for example can use branches such as osgeo/9.5, osgeo/10.0, etc.

Using UbuntuGIS and derivative release specific branches assist collaboration between Debian GIS and the UbuntuGIS and derivative teams. Changes from Debian or Ubuntu can be merged or cherry picked from their respective branches without needing to obtain the source packages to manually merge the changes from.

Tags for upstream and package releases

The tagging convention used for upstream and package releases follows the defaults of git-buildpackage.

upstream/<upstreamversion> for upstream releases, e.g. upstream/1.2.0
debian/<debianversion> for Debian releases, e.g. debian/1.2.0-1

Tags for package releases targeting derivative distributions use a distribution specific prefix followed by the package version separated by a / character:

<distribution>/<package_version>

Examples of the tagging convention for known derivatives:

ubuntugis/<debian_version>~<ubuntu_codename><revision_number> for UbuntuGIS backports based on the Debian GIS packaging, e.g. ubuntugis/1.2.0-1~trusty1
osgeo/<debian_version>~<ubuntu_codename><revision_number> for OSGeo-Live releases and backports based on the Debian GIS packaging, e.g. osgeo/1.2.0-1~xenial1

Upstream Git repositories

For some projects, like the ones hosted on GitHub or GitLab, it may be easier to forward changes made in the Debian package if this one is itself mirrored on the same platform, as a clone. In that case, the layouts may vary from package to package, and the branch that contains the Debian work will probably not be the master one. If it is not the default branch, it must be indicated in the VCS URL with the -b option.

Even when you are not using git-buildpackage, please include a debian/gbp.conf, to document the layout of the repository.

When working with upstream Git repositories, it's convenient to have the upstream repository configured as a Git remote called upstream. Fetching the upstream commit history into the package repository allows among others per commit reviews of new upstream releases, and reading extended commit messages.

When the upstream Git repository is not configured as a remote in the Debian GIS Git repository on Salsa, you may not want to push the upstream tags, because the referenced commits only exist in the upstream Git repository.