This tutorial will show you how to use Git and Sourcetree to oversee your project’s workflow.
Using Git allows each member to work on their own part of the project in parallel with other members of your team, without worrying about conflicting versions.
The analogy goes like this:
masterbranch is the “trunk” of the project - no changes are directly made here
featurebranch is an offshoot where individual members can work on some aspect in detail - once their purpose is fulfilled, they can be merged back into the
masterbranch (either directly, or via other
This way, work can be compartmentalised while minimalising conflicts and localising each member’s changes, making the process easily accountable for each member.
From the Setup tutorial, you will have been able to
clone the repository into your own machine. We will now go through how you can go about making changes.
This will be what your interface will look like immediately after cloning.
repository status by selecting it from this dropdown menu.
Now, you can
pull changes from the
remote repository into your
Pulling a branch from the repository means that you are taking that branch and updating your own repository to match the contents of the branch you pulled. This is like synchronising your files between a cloud or online drive and your machine, except you can be quite specific about what you are pulling.
For the tutorial, you can just select the
Pull icon and confirm it on the pop-up window. If you have just
cloned the repository (from the setup tutorial),
pulling will not do anything, since both repositories will be exactly the same.
branch is an instantiation of the repository that allows you to make changes separate from other
This project already has
remote branches (they are not tracked by our Sourcetree yet), which we can pull to make them
locally available. Moving from one
branch to another is known as a
On the left side pane, select
origin, and then double-click
development. A window will pop up confirming that you would like to
Checkout New Branch. Selecting
OK with the box ticked, this will create a new
local branch called
development, which will have all the developments and changes from that branch on your computer.
Now, let’s create a new
branch from this
development branch. To create a new
branch, select the
branch icon: give it a useful name that tells us exactly what it is for (we will use
fix-reversals), and confirm. Your new branch will now appear on the left under your list of branches. You will now also see on the
log that a new branch has been created.
Keep in mind that you should still try to minimise conflicts with other members of the team by restricting the scope of your changes to a single issue (in our case: only dealing with gloss lines in a dictionary file). Though some conflicts will be inevitable, you can pre-empt them effectively by just sticking to your own parts of the project.
Now you can start to make changes to the file(s) in your repository. When you
cloned your repository, you should have put it somewhere in your directory. The
branch you are currently on is the version of the repository that you can access. If you
checkout other branches, then the files will change accordingly.
You can directly access the folder of your repository by clicking
For this tutorial, we’ll use the following issue as an example.
ISSUE: We have `\gl` lines to indicate the gloss of a Warlpiri word, and `\rv` lines to indicate which English words should direct to this Warlpiri word in the 'reversed' dictionary. Historically, both functions were handled by the `gl` line, with `^` and `` used to indicate the `reversal` entry words, but this was deemed too clunky to validate. To address this, `\rv` lines were introduced: they are clones of `\gl` that have been reduced to limit the size of the reversed dictionary. The consequence is that `\gl` contains unnecessary reversal information and `\rv` is not always succinct. While this is not grammar-breaking, it is aesthetic clutter that can be fixed.
Of course, you can do this line-by-line, but you can also use script to help you out. How you can do this will be covered in another tutorial, but if you find yourself involved in reading or writing script, note the following:
It is helpful to keep a track of your changes as you are making them. DiffMerge is a great desktop tool for this: simply supply the old file and the changed file, and it will show you what the differences are (this is called a
diff). There are also online tools for doing this on the fly (copying and pasting chunks of text).
Once you have completed your changes for the day (or for the entire issue), make sure you keep a note of where those files are saved. Script files belong inside the
mini-wlp/scripts folder, and lexicon files inside the
After you have finished making our changes, you can bring all our changes from the test file into the master file.
commit is a saved state of the
branch. By dividing your work up into stages that are summarised by single
commits, you can keep track of what your work progress.
Return to your Sourcetree window and you will see that the log records that there are
Uncommitted changes (i.e. the changes we made in Step 2). Head to
Here you will see the changes that Sourcetree has detected: a new
untracked file called
clean-reversals.R (our script) and a modified
wlp-lexicon_master.txt (our lexicon file).
Notice that Sourcetree conveniently provides a
diff of all the changes; you can stage as many or as few changes as you want, but most of the time, you will want to select
You may now
commit the changes you have staged. Summarise those changes in your
commit label, make sure that
Push changes immediately to - is left unchecked, and select
You will now see your commit on the
When you are working on your own, you will be cycling through steps 2 and 3 until the aims set out by the
feature branch has been fulfilled. From there, you may proceed with the steps set out by the rest of the tutorial.
fix-reversals branch is now one commit ahead of
development (where we branched off from in Step 1). Once you have completed your work on this branch, it is time to merge back into the main
To merge, we first checkout the
Refresh your repository status. Sourcetree will let you know if there is anything new to pull (in our case, nothing - but if someone else has been working on the
development branch in the meantime, there may be new commits to
Now we will
merge our two branches: the changes in
fix-reversals will now appear in
development. If you did not need to pull anything in the last step, then this should run without any conflicts.
If someone did make their own changes to
development in the meantime, there may now be conflicts between their version and yours. Git will flag all the conflicts. Refer to the Git problem-solving tutorial on how to resolve merge conflicts.
Now we are ready to
push our files back into the remote repository (where
pulled in Step 0). Select
Push and a popup window will ask you which
branches you want to
push. If you would like your
feature branch to be available to your collaborators, you may select that to be pushed to a remote branch of the same name.
In this case, since all our work has already been merged into the
development branch, we can simply select
If you did not
feature branch (
fix-reversals), and you have no use for it any more, you may
NOTE: If you
feature branch (as in Step 8),
deleting your branch will only
delete it locally (on your machine): it will make no difference to the branch on the remote repository. To
delete a remote branch requires a
force delete, which is very dangerous since this will affect how your collaborators use that branch - always discuss with them before
deleting remote branches.
delete a branch that you are still on, so make sure you are on the
development branch (or any other branch) when you
You (and your team members) will cycle through steps 0 to 9 until the
development branch has reached a certain stage of completion. When that happens, your team may consider merging
development into the
master branch. This is basically the same process as set out in Steps 4 to 6:
master branch, right-click
development and select
Merge. There should be no conflicts as no one should have been working directly on the