Learn Git

To learn more about Git, refer to its homepage and official documentation.

Here are a couple of links to get started with Git:

• Git basics, by Atlassian

• Git immersion, a step-by-step introduction

• Pro Git, a book on Git from basic to advanced usage.

  This book is available in several formats and languages.

General information

GitLab

To browse most of our repositories, see our GitLab.

To actually contribute, you need to register. See the documentation about how we're using GitLab.

Merge policy

See our merge policy.

Repositories

Main repository

This repository contains the Tails source code and the source of the website.

For instructions about cloning and forking this repository, visit it on GitLab.

We use Git submodules, so after cloning this repository, in your new Git clone's directory, run:

git submodule update --init

For more information about our usage of Git submodules, see the dedicated section.

Configuration

Developers with write access to the repositories should:

git config --global url.git@gitlab-ssh.tails.boum.org:.insteadOf \
   https://gitlab.tails.boum.org/

We also recommend the following setting in your Tails clone since it otherwise is too easy to forget pushing updated submodules:

git config push.recurseSubmodules check

To have git blame ignore specific commits that would make its output less useful, such as automated code reformatting, run in your local clone:g ap

git config --local blame.ignoreRevsFile .git-blame-ignore-revs

Branches

Tails development uses several branches modeled a bit like the Debian development process. Here they are.

master

The master branch is mostly used to build the website. It is merged into devel and stable from time to time. We merge into master:

• Documentation improvements that affect current Tails (e.g. not the next Tails release).

• Other changes to the website (news, security advisories, layout, and so on).

• Translations of the website.

• When releasing a new Tails, the branch the release was built from (stable or testing).

stable

The stable branch is intended to contain:

• the state of the code tagged for the last stable release
• fixes for security or important bugs.

Its purpose is to prepare bugfix releases.

testing

The testing branch is used to prepare an imminent major release: at some point of the development process, the devel branch code is merged into testing, frozen, and endures careful testing and bug-fixing until this branch is considered good enough to become a stable release. The testing branch is then merged into the stable and master ones, images built and shipped and we go back to code shiny new stuff in the devel branch.

Please note that the testing branch generally has not been granted the same testing and attention as code that has made it into a stable release: please use it for testing purposes but do not rely on it for anything. No guarantee, blablabla.

devel

Large changes that need to be included in a release candidate before we release them in a major Tails release are based on the devel branch. This branch will never get released; instead, code from it will be merged into testing and then into a real release.

Please note that the devel branch can be broken, have awful security problems and so on. No guarantee, blablabla.

The master branch is merged into devel from time to time.

Topic branches

We generally use topic branches called NNNNN-*, with "NNNNN" being the main issue addressed by the branch. Once ready, a topic branch is merged (with --no-ff) into the appropriate branch (generally devel). Until it has been merged, a topic branch's history may be rewritten, e.g. it may be rebased on top of devel.

Unless there are good reasons to do otherwise, bugfix branches must be forked off the stable branch, while feature branches should be forked off the devel branch.

If you intend to work on a branch not really meant to be proposed to a merge at first, like an experimenting branch that you still want to push to share with other developers, you can prefix its name by the keyword wip/. It will make it clear to everyone that this branch shouldn't be merged before being renamed, and our Jenkins instance will not build nor test it.

Promotion material

This repository contains Tails promotion material.

For instructions about cloning and forking this repository, visit it on GitLab.

Puppet code

Puppet code

This repository contains all the puppet manifests and data that is managing the Tails infrastructure.

For instructions about cloning and forking this repository, visit it on GitLab.

All the Puppet modules we use are tracked as Git submodules in this repository.

Puppet modules

We use a lot of third party Puppet modules and maintain several of our own. For example, puppet-tails is the Puppet module containing all the profiles we use to manage Tails infrastructure, including classes such as tails::profile::reprepro and tails::profile::base.

For instructions about cloning and forking the puppet-tails repository, visit it on GitLab.

Other repositories

Most other public Tails Git repositories are on our GitLab.

Submodules

We use Git submodules to track external repositories from the main Tails source tree.

The main practical consequence thereof so far, for most Tails contributors, is that one should generally run the following command after checking out a branch:

git submodule update --init

For more information, see:

• the chapter about submodules in the Pro Git book;

• the git-submodule(1) man page.

Creating a new repository

In the vast majority of cases, your new repository will be hosted our GitLab.

If you want to modify files that are already in one of our Git repositories, create your own fork of this repository from your account on our GitLab.

Else, if you want a new repository for a different project or a new team, request it from the Tails system administrators. Include the following information in your request:

• your GitLab user name
• the preferred name of the new repository
• which teams and individuals should have read access to this new repository
• which teams and individuals should have write access to this new repository

Once your repository has been created, clone it:

• If you want to encrypt the content of your new Git repository with OpenPGP, go through some arcane initialization ritual to reach wisdom, bliss and enlightenment.

• Otherwise (lucky you!), find your new repository and instructions to clone it on GitLab.

Initializing a git-remote-gcrypt repository

Clone the new, empty repository in a way that tells Git it's going to be encrypted:

git clone gcrypt::git@gitlab-ssh.tails.boum.org:$REPOSITORY

Change directory into the newly cloned repository:

cd $REPOSITORY

Decide whether you want to hide to the immerda administrators which OpenPGP keys this repository will be encrypted for (note that this has severe usability drawbacks). Skip to the next step if you really want that. Otherwise:

git config gcrypt.publish-participants true

Tell Git which OpenPGP keys the repository will be encrypted for:

git config gcrypt.participants "LIST OF OPENPGP FINGERPRINTS"

Write some setup instructions for your team-mates, e.g. copy and paste the git config command(s) you have just run:

editor README

Add these setup instructions to the repository and commit:

git add README && git commit -m 'Add setup documentation.'

Push:

git push -u origin master

Troubleshooting

First, check with your team-mates: in some cases they can help you troubleshoot your problem, and confirm whether the problem is on your side or on the server side. If that is not enough, get in touch with the Tails system administrators.