HomeContact
Archive
Using SourceTree and Git for Research (Part 1)
Jon Page
May 31, 2013
3 min

Table Of Contents

01
Step 1: Setup LaTeX file
02
Step 2: Setup a Bitbucket account
03
Step 3: Install SourceTree
04
Step 4: Setup your repository
05
Step 5: Making a change to the LaTeX file
06
Step 6: Viewing your history
07
Next Steps

A Version control system (VCS) helps you manage changes to documents and programs. This goes beyond using Track Changes in Microsoft Word. For example, you can revert to older versions of a LaTeX document or program written in Stata, SAS, or R. With a distributed version control system (DVCS), you can track changes to all your documents and programs while collaborating with coauthors. Bitbucket offers for free an unlimited number of private repositories with up to 5 collaborators. If you authorize an academic (*.edu) email account you get unlimited contributors! A popular alternative is Github, but since Github does not offer free private repositories (and keeping your research private is important!) we will use Bitbucket. Bitbucket makes use of two DVCSs: Mercurial (Hg) and Git. We’ll be using Git for this tutorial, but you could use Mercurial instead if you prefer (intro to working with Mercurial). To make using git (and hg) a breeze, we will be using SourceTree, the free tool by Atlassian (makers of Bitbucket).
Using a DVCS allows you to link a repository to the documents on your local machine. This repository will allow you to track changes to your documents and keep a record of your document history. To see how this system works. This tutorial will trace the following steps:

  1. Set up a project folder with a basic LaTeX file.
  2. Set up a Bitbucket account.
  3. Install SourceTree.
  4. Create a git repository using SourceTree.
  5. Make a change to our LaTeX file.
  6. Summarize basic features for reviewing changes.

Part 2 of this tutorial will cover connecting this repository to a Bitbucket.org repository to put the D in DVCS and take a look at collaborating with coauthors.

Step 1: Setup LaTeX file

  1. Create a new LaTeX file named “itn.tex”.
  2. Place this file in a folder that will only be used for this project.
  3. Place the following sample text in the file and save it.
\documentclass{article}
\title{International Trade Network}
\author{Jonathan Page}
\begin{document}
  \maketitle{}

  \section{Introduction}
  Careful analysis of the topology of the international trade network (ITN) is necessary in order to
  identify stylized facts which a theoretic network model of international trade should be able to replicate.
  Properties of networks are tightly related to the relevant network formation process. Determining the most
  appropriate network formation process can provide depth to related empirical analysis.

\end{document}

Step 2: Setup a Bitbucket account

Go to bitbucket.org and sign up for a new account (if you don’t already have one).

bitbucket_frontpage
bitbucket_frontpage

Step 3: Install SourceTree

Go to https://sourcetreeapp.com/ and click the large “Download SourceTree Free” button in the middle of the page. Your button may appear different if you are using Windows.

SourceTree
SourceTree
Click the downloaded dmg file and drag the SourceTree application to your Applications folder.
installSourceTree
installSourceTree
Open the SourceTree application. You will see a screen similar to the one below. Fill this form out with your fullname and the email address you used to setup your Bitbucket account. Make sure both check boxes are checked to allow SourceTree to manage your Mercurial and Git configurations and to agree to the license agreement. Click “Next”.
Setup_SourceTree
Setup_SourceTree
Enter your Bitbucket account information and click “Next”.
Setup2_SourceTree
Setup2_SourceTree
Click “Finish” to complete the initial setup process.

Step 4: Setup your repository

Open finder and find the folder that contains your LaTeX file. Drag this folder onto the SourceTree application window. This will open the following dialog.

new_repo_dialog
new_repo_dialog
Change the “Repository Type” from “Mercurial” to “Git” (you can also change the default bookmark name if you like). Click “Create”.

Add “itn.tex” to the staging area

Double-click the project to open the project view. Click “Add” to add all files in the folder to the repository.

project_view
project_view
Notice that “itn.tex” has been moved from “Files in the working directory” to “Files staged in the index”. This means that if we commit changes, changes to “itn.tex” will be updated to the repository.
itn_staged
itn_staged

Commit to initialize the repository

Press the “Commit” button.

commit
commit
This will bring up the dialog seen below. Add a meaningful message (always a good idea). Click “Commit”.
commit_message
commit_message

Step 5: Making a change to the LaTeX file

Now we want to see how this version control system deals with changes. Add the following paragraph to “itn.tex”:

In the analysis of international trade as a network phenomenon, we must answer the question of how the network
structure is determined. More precisely, if we assume the network structure is given to us exogenously, our
analysis will focus on the game played on the given network. If, however, the formation of the network structure is
endogenous, our analysis must broaden to consider the formation process. This survey focuses on what information
the network itself can provide regarding the formation process.

Save “itn.tex”. Open the SourceTree application. Notice that “itn.tex” now has a new icon beside it to indicate it has been changed.

modified
modified
Click the file. This will show the changes you have made on the right.
click_file_stage
click_file_stage
Click “Stage File” or “Add”. Click “Commit”, choose an appropriate message and click “Commit” to commit these changes to your repository.

Step 6: Viewing your history

Click the clock symbol to view the log.

log_view
log_view
Click the two log entries to see the changes that were added at each commit. Click “External Diff” to open another view of the differences between the selected commit and the one preceding it. Close the “External Diff” window.
log_view2
log_view2

Next Steps

We’ve covered quite a bit here, but there is much more to learn. Though our example worked with a LaTeX source file, you could follow the same process with any filetype. In fact, version control systems were developed with programmers in mind. As a result this is the perfect way to manage your source files for Stata, SAS, R, Python, HTML, etc. Here are a few git resources to get you started:

Be sure to check out the next part of this tutorial as we connect our repository to the Bitbucket site and collaborate with a coauthor. Any tips or nagging questions? I would love to hear them!


Tags

#bitbucket", "#git", "#sourcetree

Related Posts

Using SourceTree and Git for Research (Part 2): Bitbucket
June 06, 2013
2 min
© 2022, All Rights Reserved.

Quick Links

About UsContact Us

Social Media