Using Git

Apertium development code is kept in GitHub. To browse the repositories in a more compact fashion, visit the source browser. The following shorthands are used there:

• trunk — this holds the main development tree for released translation pairs,
• languages — this holds the main development tree for individual languages (depended on by translation pairs),
• incubator, nursery, staging — these hold work-in-progress modules (mostly language pairs) that have not yet made it into trunk or languages.

Quick cheatsheet

Developers working on a few pairs/languages

For each pair/language, initial checkout/clone: git clone https://github.com/apertium/apertium-<langcode or pair>.git

If there is too much history and you don't need it, you can do git clone --depth N https://github.com/apertium/apertium-<langcode or pair>.git to get only the last N commits in history.

To make a commit:

1. git add <files that you changed>
2. git commit -m <message> (commits will be stored to your computer)
3. git push (commits will be sent to GitHub)

Note: Steps 1 and 2 above can be done multiple times even when offline, and then all the commits can be pushed at once when online.

To see other people's changes: git pull

Developers working on many pairs/languages (1)

Note: apertium-all will get literally everything. Other options are apertium-languages, apertium-trunk, apertium-staging, apertium-incubator, apertium-nursery, apertium-tools.

Initial checkout/clone: git clone --recurse-submodules --shallow-submodules --depth 1 https://github.com/apertium/apertium-all.git

(Change --depth 1 to --depth N to get the last N commits)

To make a commit:

1. git submodule foreach 'git commit -a -m <message>'
2. git submodule foreach 'git push'

Developers working on many pairs/languages (2)

If submodules are too cumbersome you can also just set up the apertium-style directory structure manually and use scripts to checkout the contents of individual parts.

Working with branches

Branch new-feature exists on the repository but not in your clone.

If you used --depth while cloning

git fetch --unshallow origin new-feature
git checkout new-feature

If you did not use --depth while cloning

git checkout new-feature

Avoid entering password every time

SSH keys work exactly like on SourceForge. You will have to clone the repository again, with the URL git@github.com:apertium/apertium-whatever.git.

Learning to use git

If you have not used git before, or are uncomfortable with using git, these resources can help you:

• https://try.github.io/levels/1/challenges/1 (interactive, short, lets you practice with a mock repository, covers most things commonly needed but nothing advanced)
• http://rogerdudler.github.io/git-guide/ (less text/explanation, more commands/links, good for reference or brushing up forgotten git knowledge)
• http://gitimmersion.com/ (divided into detailed 'lessons', like a self-paced online course, intermediate to advanced level)
• https://www.ibm.com/developerworks/library/l-git-subversion-1/index.html (git tutorial for SVN users, long and verbose)

If you have further questions:

• See #Advanced git commands
• Ask Apertium's #In-house git help
• Or, of course, ask on StackOverflow, read the git documentation, etc.

Learning to use GitHub

If you have not used GitHub before, or are uncomfortable with using GitHub, these resources can help you:

• https://services.github.com/on-demand/intro-to-github/ (intro to using GitHub, assumes a little git knowledge)
• https://guides.github.com/ (various topics at all levels)

The official GitHub documentation is extensive and helpful. Specific questions can be answered by #In-house git help.

Avoiding git completely

For some reason, if you don't like git or don't want to learn git or are unable to learn git, you can avoid using git completely for all GitHub repositories. You will simply need to perform a fresh SVN checkout with the correct URL and you can continue using the same SVN commands and workflow that you are used to. This page explains how to do this.

Advanced git commands

Removing/undoing all changes since the last commit

git stash

What this does: If you've added new files to be committed, the're "unadded" (but not deleted); if you've made changes to tracked files, the changes are removed so they look like what they were in the last commit. (Bonus point: changes removed with stash can be re-added if you change your mind with git stash pop.)

Add -p to select chunks of each file that should be stashed.

Reverting your branch to the state of a remote branch

If on branch master, you want to get your repo to what the remote master looks like:

git reset --hard origin/master

Use case: say you're in the master branch, and have done a bunch of local commits/merges that you haven't pushed. Now you're stuck somehow, maybe you've got a merge conflict or something and you can't figure out the damn commands to get out of it all. You just want your repo to look like you just checked it out. Then you can run this command. It'll work in the middle of merge conflicts, with staged-but-not-committed files, etc.

If you reset to origin/master from some other branch, that branch will now be at the same commit as the remote master (and any other committed changes in that branch will be lost).

If you're on branch somefeature and want to revert to the remote somefeature, then this is the command:

git reset --hard origin/somefeature

Removing/undoing your changes to a certain file / path

 git checkout -- <path>

If "path" is ".", you undo all your changes to version controlled files in that directory and sub-directories:

 git checkout -- .

If you've first done git add (to "stage your changes", so some file is listed under Changes to be committed), you first need to do git reset to unstage the changes, then checkout in case you had changes to files already tracked. So to do that for the whole dir:

git reset HEAD .
git checkout -- .

Merge conflict: Throw away local changes

 git checkout master <path>
 git commit
 git merge master

(The last command should now do nothing, just say you're fully merged.)

In-house git help

Method 1: IRC

• user Shardulc (talk), IRC nickname 'shardulc'
• user Sushain (talk), IRC nickname 'sushain' / 'sushain97'

Method 2: Email

• user Shardulc (talk), email <shardul DOT chiplunkar AT gmail DOT com>
• user Sushain (talk), email <apertium@skc.name>

Method 3: Contact via mailing lists, especially apertium-stuff