Using Git

From Apertium
Jump to navigation Jump to search

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[edit]

Developers working on a few pairs/languages[edit]

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)[edit]

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)[edit]

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[edit]

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

If you used --depth while cloning[edit]

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

If you did not use --depth while cloning[edit]

git checkout new-feature

Avoid entering password every time[edit]

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[edit]

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

If you have further questions:

Learning to use GitHub[edit]

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

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

Avoiding git completely[edit]

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[edit]

Removing/undoing all changes since the last commit[edit]

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[edit]

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[edit]

 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[edit]

 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[edit]

Method 1: IRC


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