Introduction

There are numerous methods to initiate a new Git repository. The experienced user may operate entirely within a command terminal, while those just starting with Git may use a combination of the web interface and a graphical user interface (GUI). In this brief walkthrough, I will demonstrate one method for initializing a Git repository for the DANTE Project.

Installing Git

Before you begin, make sure Git is installed on your local computer. You can install git for Windows or Mac OS X by downloading the corresponding installer. Git may be installed over the terminal with Linux by issuing the following command:

apt-get install git

Creating an Empty Repository

We’ll begin by initializing an empty repository through the DANTE GitLab Project Page. From the DANTE project page select either the Vignette or Dataset subgroups by clicking either of their links.

Once you are in one of the subgroup landing pages, initiate a new repository with the green “New Project” button.

In the GitLab new project interface fill out the project name, create a 1 or 2 sentence description of the dataset or vignette, and make sure the project is public. When possible, simplify the name of datasets to acronyms and employ brief descriptions separated by hyphens (-) for vignettes. In this example I named the repository new-dataset.

Complete initialization by clicking “Create Project”. Now you will be greeted by the initialized, yet empty, repository landing page. This page contains several terminal based approaches to populating the new repository. We’ll be going into RStudio and employing the “Push an existing folder” options.

RStudio Default Terminal

At this point we can continue solely in RStudio. If you’re using RStudio with Windows: 1) make sure you’ve installed Git using the most recent installer, and 2) enabled Git Bash as the default terminal option within RStudio. From the RStudio menu select Tools > Global Options to bring up the options menu. Select the Terminal tab and then “Git Bash” from the drop down menu as indicated in the image below.

Creating a New Project

Now create a new project with the RStudio menu using File > New Project. This will bring up the new project menu. Select “New Directory” on the first menu, and “New Project” on the second menu. Then, enter the dataset or vignette name (preferably the same used to name the GitLab repository) on the final menu.

Creating a New Rmarkdown Document

With the RStudio project created, we can start our dataset page or vignette. Begin by creating a new Rmarkdown file from an existing template. For this example we’ll employ the Dante Dataset template from danteSubmit, however, you can use any provided template or simply create a project with scripts containing functions documented with roxygen2. From the RStudio menu select File > New File > Rmarkdown .... This initializes the new Rmarkdown window where you can select the desired template.

Clicking “OK” will create the Rmarkdown template you selected. You may click “Knit” to view the stylings for the selected template. This will “knit” the Rmarkdown template into the output file (in this case a HTML).

You may begin filling out the Rmarkdown skeleton, however, it’s a good time to push our our skeleton and base HTML output into the empty GitLab repository.

Pushing our Files

Now we will use the RStudio terminal to initiate the Git repository. Click the “Terminal Tab” in the Console window.

Inside the terminal window we can link our repository and push files using the “Push an existing folder” commands from our earlier step. Making sure you are in the appropriate directory within RStudio’s terminal, run the following commands.

git init
git remote add origin git@gitlab.com:dante-sttr/dataset-pages/new-dataset.git

At this point, you may add all project files by issuing git add . in the terminal, however, you may have large or otherwise non-essential files you do not want to populate the repository with. These may include large documents, raster images, or databases used to generate figures or other Rmarkdown elements. You can employ the RStudio Git interface to manually add files in your project.

Although we just linked our repository via the terminal with the prior two commands, RStudio has yet to recognize our project is under version control. Closing and reopening the project with the project drop down menu will force RStudio to recognize the Git repository and make the built-in Git interface available for our project. Select the project drop down menu in the upper right corner of RStudio and close, then re-open the project (it will be listed in the recent project list).

This will initiate the RStudio Git tab.

The Git tab tracks file alterations, additions, and deletions. Clicking “Diff” in the Git tab will bring up RStudio’s Git interface. The Git GUI allows users to manage and view file changes, make commits, and push changes to your repository. You can stage changes and add or delete files by checking their corresponding boxes. At this point, stage the initial Rmarkdown .Rmd and .HTML files by checking their boxes. It’s customary to identify the first commit with the message “initial push”, but you can write whatever you want. Lastly, click commit to finalize your changes.

Normally, you may push your committed changes directly inside the RStudio Git GUI, however, for the first push you must use the terminal. Close out the Git GUI and return to the RStudio terminal. We’ve already added and committed the new Rmarkdown files, but we have to run the final command listed in “Push an existing folder” to push and set the origin and and master repository.

git push -u origin master

Checking the New Repository

Lastly, use your web browser to navigate back to the formerly empty repository; you should be greeted by the repository directory and recently committed files.

Success.

Further Reading

Although we successfully initiated a GitLab repository, this is only the beginning of Git and RStudio. Google searches will serve you well when trying to expand your understanding of Git, but the official Git Reference Manual and GitLab Docs are good places to start. RStudio Support’s Version Control with Git and SVN will get you started with integrating Git and RStudio. Happy Git and GitHub for the useR presents a more in-depth look at RStudio integration. As a first step I would suggest setting up SSH keys on your GitLab account and integrating them with RStudio.

References