[[!meta title="Git repositories"]]

<div id="intro">

<p>Tails and its website are developed in numerous Git repositories.</p>

<p><span class="application">Git</span> is a distributed version control
system. It allows several people to work on the same source code and
handle changes in a distributed and efficient way.</p>

</div>

[[!toc levels=3]]

<a id="learn_Git"></a>

Learn Git
=========

<p>To learn more about <span class="application">Git</span>, refer to
its <a href="http://git-scm.com/">homepage</a>, and <a
href="http://git-scm.com/documentation">official documentation</a>.</p>

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

- An [interactive introduction](https://try.github.io/) to Git
- [Git basics](https://www.atlassian.com/git/tutorial/git-basics), by Atlassian
- [Git immersion](http://gitimmersion.com/), a step-by-step introduction
- Pro Git: [online](http://git-scm.com/book),
  [PDF](https://github.s3.amazonaws.com/media/progit.en.pdf), a book on Git from
  basic to advanced usage. This book is available in several languages. Among others:
  [German](http://git-scm.com/book/de), [French](http://git-scm.com/book/fr), [Português](http://git-scm.com/book/pt-br) (Brasil)
- [OpenHatch Missions: Using Git](https://openhatch.org/missions/git), concrete
  exercises to train yourself in using Git.
- [Git For Ages 4 And
  Up](http://mirror.linux.org.au/linux.conf.au/2013/mp4/Git_For_Ages_4_And_Up.mp4),
  a video on learning Git.

<a id="general-information"></a>

General information
===================

Git hosting setup at immerda
----------------------------

Documentation for our Git hosting setup at immerda:

* [main documentation](https://wiki.immerda.ch/index.php/GitRepositoriesImmerda)
* [SSL and SSH fingerprints](https://www.immerda.ch/infos/certs.html)

Merge policy
------------

See our [[contribute/merge_policy]].

Caution!
--------

If you intend to prepare Tails releases, you'll need to make
the development team signing key the default one for Git tags:

	git config user.signingkey A490D0F4D311A4153E2BB7CADBB802B258ACD84F

Creating a new repository
-------------------------

Create a new repository at immerda.

Repositories
============

<a id="main-repo"></a>

Main repository
---------------

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

Anyone can check it out like this:

	git clone https://git-tails.immerda.ch/tails

Developers with write access to the repositories should instead:

	git clone boum_org_amnesia@webmasters.boum.org:wiki.git

And then, in any case, in your new Git clone's directory:

	git submodule update --init

For more information about our usage of Git submodules, see
[[the dedicated section|git#submodules]].

We have a [web interface](https://git-tails.immerda.ch/tails/)
available for the main repository.

### Configuration

Developers with write access to the repositories should:

	git config --global url.tails@git.tails.boum.org:.insteadOf \
	   https://git-tails.immerda.ch/

<a id="branches"></a>

### Branches

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

<a id="master_branch"></a>

#### 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|contribute/how/documentation]] that
  affect current Tails (e.g. not the next Tails release).
- Other changes to the website ([[news]], [[security advisories|security/]], layout, and so on).
- [[Translations|contribute/how/translate#website]] of the website.
- When [[releasing a new Tails|contribute/release_process/]], 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 minor releases.

#### testing

The `testing` branch is used to prepare an imminent 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

Most of the development work that is done in Tails, is done in 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 use topic branches called `bugfix/*` and
`feature/*`, respectively aimed at fixing a single bug and
implementing a single new feature. 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 latest stable release tag, 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, so you won't get notifications for a branch that you know is
breaking the build and/or the test suite.

<a id="promotion-material"></a>

Promotion material
------------------

This repository contains Tails [[promotion
material|contribute/how/promote/material]].

Anyone can check it out like this:

	git clone https://git-tails.immerda.ch/promotion-material

Developers with write access to the repositories should instead:

	git clone boum_org_amnesia@webmasters.boum.org:promotion-material.git

We have a [web interface](https://git-tails.immerda.ch/promotion-material/)
available for the promotion material repository.

<a id="puppet"></a>

Puppet modules
--------------

Those who have SSH access to these repositories must configure their
SSH client a bit, e.g.:

	Host git.puppet.tails.boum.org
		HostName d53ykjpeekuikgoq.onion
		ProxyCommand torsocks monkeysphere ssh-proxycommand %h %p

### tails

This is the main *public* Puppet module to manage Tails infrastructure,
including classes such as `tails::reprepro` and `tails::whisperback::relay`.

Anyone can check it out like this:

	git clone git://git.puppet.tails.boum.org/puppet-tails

Developers with write access to the repositories should instead:

	git clone gitolite@git.puppet.tails.boum.org:puppet-tails

### Other Puppet modules

We use and publish a lot of other Puppet modules. See the section
about our [[other repositories|git#other-repositories]].

### tails_lizard_manifests

Developers with access to the APT secrets can check it out like this:

	git clone gitolite@git.puppet.tails.boum.org:puppet-lizard-manifests

### tails_secrets_apt

Developers with access to the APT secrets can check it out like this:

	git clone gitolite@git.puppet.tails.boum.org:puppet-tails_secrets_apt

### tails_secrets_whisperback

Developers with access to the WhisperBack secrets can check it out like this:

	git clone gitolite@git.puppet.tails.boum.org:puppet-tails_secrets_whisperback

<a id="other-repositories"></a>

Other repositories
------------------

All other public Tails Git repositories are at
<https://git-tails.immerda.ch/>.

Unauthenticated access is of the form:

	git clone https://git-tails.immerda.ch/$REPOSITORY

Developers with write access to the repositories should instead:

	git clone tails@git.tails.boum.org:$REPOSITORY

<a id="submodules"></a>

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](https://git-scm.herokuapp.com/book/en/v2/Git-Tools-Submodules)
  in the *Pro Git* book;
* the [`git-submodule(1)`](http://manpages.debian.org/git-submodule)
  man page.
