# Some basic notions about git

## Getting an account on &salsa;

git commit access requires the creation of an account on the &salsa; server. This is as simple as opening &url-salsa; and clicking on Sign in / Register in the top right corner.

Official Debian developers will probably use the same login as their Debian login, but must go through the account creation process anyway.

## Installing git and myrepos

Translators need to install git on their system. Just do `apt install git`.

&d-i; contributors who want to work on the code of the installer (so not just translation work), additionally need to install myrepos by `apt install myrepos`.

Users of non-Debian Linux distributions will probably easily find installation sources for git and myrepos in their distribution packages list.

## Using git to get and commit files

Once their account is allowed to write to the project, translators can download the translation files using the checkout commands mentioned in translators.

Developers can download the full project source tree using git and mr commands as detailed in maintainers. Note, that this is not necessary for translators!

`ssh` connections require you to use RSA key-based authentication to connect to &salsa;.

If you don't have an existing SSH keypair on your local system, you must create one with the `ssh-keygen` command:

    spongebob@mykerinos:~$ ssh-keygen -t rsa
    Generating public/private rsa key pair.
    Enter file in which to save the key (/home/spongebob/.ssh/id_dsa):
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    Your identification has been saved in /home/spongebob/.ssh/id_rsa.
    Your public key has been saved in /home/spongebob/.ssh/id_rsa.pub.
    The key fingerprint is:
    8d:6d:14:72:72:07:01:6a:85:de:97:d3:aa:b2:ee:4a spongebob@mykerinos

In the example above, the user spongebob creates a SSH RSA keypair, which is saved in a directory named `.ssh` in his/her home directory.

This keypair is protected by a passphrase. The passphrase has to be entered each time the keypair will be used to connect to a remote host. Take care to choose a non trivial passphrase.

After doing so, the public part of that keypair must be put in your account on &salsa;.

In case users have problems with GIT checkouts/commits, they can ask for help, either on IRC, &irc-channel; or by mail with the &i18n-coords;.

## Core &d-i; and various levels packages repositories checkout command lines

Typical non anonymous and anonymous checkout command lines for &d-i; and related packages are listed in translators.

Below is an example of a checkout of the d-i GIT repository, containing the po files for level 1:

    user@host:~$ &git-clone-d-i-repo;
    Cloning into 'd-i'...
    remote: Counting objects: 405013, done.
    remote: Compressing objects: 100% (72424/72424), done.
    remote: Total 405013 (delta 316140), reused 404965 (delta 316098)
    Receiving objects: 100% (405013/405013), 187.52 MiB | 199.00 KiB/s, done.
    Resolving deltas: 100% (316140/316140), done.
    user@host:~$

After this the `d-i` directory contains all files from the repository. Updating this directory later needs running `git pull`:

    user@host:~$ cd d-i
    user@host:~/d-i$ git pull
    Already up-to-date.
    user@host:~/d-i$

Now find the po translation files in the subdirectories under packages/po.

    user@host:~/d-i$ cd packages/po/sublevel1
    user@host:~/d-i/packages/po/sublevel1$

Just update the local copy:

    user@host:~/d-i/packages/po/sublevel1$ lokalize fr.po
    .../...

(Use Lokalize or any other gettext utility, see gettext-tools for details about gettext files handling, editing and maintenance tools.)

Once you have saved the modified version of the file, the status can be displayed with the `git status` command:

    user@host:~/d-i/packages/po/sublevel1$ git status -s
     M  fr.po
    user@host:~/d-i/packages/po/sublevel1$

The above means that `fr.po` includes uncommited modifications. The changed files need to be added to the staging area by `git add filename`. Then commit the modifications by using the `git commit` command:

    user@host:~/d-i/packages/po/sublevel1$ git add fr.po
    user@host:~/d-i/packages/po/sublevel1$ git commit -m "Insert a senseful commit message here, like 'Updated french translation'"

Now you need to push your changings to the remote GIT repository:

    user@host:~/d-i/packages/po/sublevel1$ git push

In general, a few recommendations can be made to translators:

- Always use the `git pull` before working on a file or directory. This will minimize conflicts in case a file is changed in the repository while they work on it;

- Always use the `git status` command before committing changes, to be sure that only relevant changes are committed.

## Changelog entries handling

When committing translations directly to GIT repositories for Debian packages, translators must update the `debian/changelog` file accordingly.

Each change in Debian packages has to be documented in the `debian/changelog` file.

However, this does not apply to level 1 translations, that is the &d-i; core packages translations. For these translations, no changelog updates are needed by translators.

Below is an excerpt of the `changelog` file for &base-config;:

    base-config (2.39) UNRELEASED; urgency=low

      * Updated translations:
        - Croatian by Krunoslav Gernhard

     -- Christian Perrier <bubulle@debian.org>  Sat, 24 Jul 2004 08:14:13 +0200

    base-config (2.38) unstable; urgency=high
    .../...

This gives the following information:

- the last released version of the package is 2.38. The GIT repository currently contains the future unpublished 2.39 release;

- the only change which occurred since 2.38 is the update of the Croatian translation (made by Krunoslav Gernhard);

- the committer of this change was Christian Perrier.

Different Debian packages may use slightly different methods and styles for `changelog` maintenance. When working with GIT repositories, using UNRELEASED for the last entry is highly recommended for new unpublished changes.

Using the `debchange` utility from the devscripts Debian package for handling `changelog` entries maintenance is also highly recommended..