Git is a version control system, which helps us keep track of and coordinate changes to various files. GitLab is a Git hosting and web-based management service for projects using Git, and SourceTree is a multi-platform desktop client that makes interacting with Git and GitLab more convenient. So roughly speaking, SourceTree is to Git (the technology) and GitLab (a service provider) what desktop clients such as Microsoft Outlook are to e-mail (the technology) for and Gmail (a service provider).
Like e-mail, there are many service providers and desktop clients. For the Warlpiri dictionary project, we use this particular combination. Thus, screenshots in this onboarding document refer to these particular software and services (please do let us know if these screenshots and instructions become out of date).
Lastly, if you do not already have a strong preference for a text editor (e.g. TextWrangler, Notepad++), we also recommend downloading and using Sublime Text. Unlike TextWrangler (macOS-only) or Notepad++ (Windows-only), Sublime Text is cross-platform, so we will also use Sublime Text in various screenshots below.
Go to https://www.sublimetext.com/3, where you’ll find various download links for Sublime Text. Click on the link relevant for your platform, e.g. OS X.
If you are on a relatively-modern Windows machine (post-2010), you will likely want the 64 bit version.
Sublime Text Build 3176.dmg. Open this file, and drag the
Sublime Text.appcontained in this image your Applications folder (a shortcut is usually provided within the image).
Sublime Textto launch it.
Sublime Text Build 3176 x64 Setup.exe. Open the setup wizard and follow the instructions to install it in your
Porgram Files. Once complete, click
Start Menu, and wherever you decide to create a shortcut. Click on the
Sublime Texticon to launch it.
To generate a new SSH key pair on OS X:
Open up the Terminal app and enter the following command (replacing firstname.lastname@example.org with your e-mail):
ssh-keygen -t rsa -C “email@example.com” -b 4096
You will then be asked where you’d like to save the key. Hit Enter/Return to leave this as the default place (/Users/your-username/.ssh/id_rsa).
Enter a passphrase (minimum 5 characters) which you will be asked for anytime when interacting with the generated key, and hit Enter/Return.
You now need to copy and paste your public key to GitLab (you may skip ahead to create an account and do this step once you are prompted to enter your SSH key). To copy the public key (assuming you saved it in the default place), run the command:
pbcopy < ~/.ssh/id_rsa.pub
To generate an SSH key in Windows requires downloading a special program called
puttygen.exefrom “http://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html” (get the 64-bit version unless you are using a very old machine). You can save it in your usual Downloads folder.
puttygen.exe. You should be faced with the following interface.
Key, make sure
SSH-2 RSAis selected.
Number of bits in generated key.
Key passphrasewhich will be used to authenticate access to the private key in the future. There are no character restrictions, so use just use common sense as with generating any other password.
C:\Users\your-user-id). This directory should also contain your
Registertab in order to create a GitLab account.
After the initial registration, you’ll be asked to confirm your e-mail address. So check the inbox of the e-mail you signed up with for an e-mail from GitLab with a link to their confirmation page.
After GitLab confirms your e-mail, you’ll be taken to the Sign In page again, where you may now sign in with your newly-created account.
Now we need to enter your SSH key under your account. Got to your
User settings by clicking the icon on the top right and selecting
On the left sidebar, select
Copy your SSH key (from your generator), and paste it in the field labelled
Typically starts with "ssh-rsa ...". Enter a name for your key and select
Sourcetree_2.7.6.zip), into your Downloads folder (or, elsewhere if you had specified the destination). Unzip this file, and drag the resulting
Sourcetree.appinto your Applications folder.
Sourcetreeapplication icon to launch it.
You will have downloaded a file named
SourceTreeSetup-2.6.10), in your Downloads folder (or, elsewhere if you had specified another destination). Open it, and it will automatically launch SourceTree.
If/when SourceTree says that it cannot find an installation of Git, click the option to install an
Embedded version of Git.
Enter the passphrase you came up with when you generated the SSH key.
In this section, we will introduce some Git terminology while also setting up your own copy of the
mini-wlp repository for the remaning part of the onboarding exercises. Iin fact, we’ll create two copies (we’ll clarify this shortly).
First, go to https://gitlab.com/coedl/mini-wlp.
A common way to refer to a Git repository hosted on the web is via the host (e.g. GitLab, GitHub), the owner (e.g
coedl), and the name of the project (e.g.
https://gitlab.com/coedl/mini-wlp. As a new member, you are currently unlikely to have write access to this
mini-wlp owned by
coedl/mini-wlp is a public repository, everyone has read access. So we can create a copy (a fork) by forking
coedl/mini-wlp into your newly-created account, i.e. creating
your-user-name/mini-wlp, to which you do have write access (note ‘fork’, just as ‘copy’, is both a noun and a verb; this type of conversion will be a recurring theme).
Forkbutton on the project home page.
your-user-name. Click on the only available namespace to continue.
your-user-name/mini-wlp. Notice that the address also reflects the ownership, which means a) you are free to modify this repository however you wish and b) these modifications will have no effect the original repository,
your-user-name/mini-wlpto your computer
The 2nd copy of
mini-wlp you will create is a local version of the GitLab repository
your-user-name/mini-wlp. Creating this local version is cloning
your-user-name/mini-wlp (or creating a clone thereof), and we will use SourceTree to help us do this.
Side note. Fork vs. clone meant different concepts historically (whether or not technically git implemented them differently), where ‘fork’ meant that you were creating a copy whose changes will not be merged back into the original repository, while ‘clone’ denoted that they would be (and you had permission to do this merge).
However, this distinction becomes less clear-cut with the advent of hosts such as GitHub and GitLab. For example, GitLab allows for forkers to request that changes in the forked repository be merged back into the original repository (via a merge request), so the historical concept of ‘fork’ may not always hold.
In our case, this distinction does hold, as we will only send changes you do on your cloned copy of
your-user-name/mini-wlp back to the your forked copy on GitLab (and you have permission to do so, since you own it). These same changes received by your forked copy on GitLab, however, will not be merged back into
coedl/mini-wlp, as we created the fork just for the onboarding exercise.
Retrieve the address of your forked
mini-wlp repository, by going to the main page of your repository (e.g.
SSH in the dropdown on the left of the address, and clicking the
Copy URL to clipboard icon on the right of it:
Switch from your browser to the SourceTree application. Click the
File menu, then click
New..., and then
Clone from URL. This will present you with the forms below. Paste the URL copied in step 1 into the
Source URL field, and the rest should be automatically completed by SourceTree for you (you may need to enter your GitLab account password). The default settings will suffice for this onboarding exercise. Note. Do take note of where the
Destination Path is.
After SourceTree has completed cloning, it will open a new window showing the
History of the repository:
In your Finder (macOS) or Windows Explorer (Windows), you may browse to location of the
Destination Path (e.g.
/Volumes/data/mini-wlp in our Clone a repository form in Step 2), and see the files associated with the repository:
Congrats! 🎉🎉🎉 You are now ready to start making changes! Head to Git Workflow to for a tutorial of how to work with Git.