Previous chapter
Git Version ControlBasic Git Workflow
Next chapter

Basic Git Workflow

In this section we discuss a basic Git workflow which covers the following steps:

  1. Create a new Git(hub) repository
  2. Clone a remote repository.
  3. Change repository contents.
  4. Commit changes.
  5. Push changes to the remote.
  6. Pull changes from the remote.

These steps cover the most basic to change an existing Git repository and stay up-to-date. We will show these steps using the command line interface as well as the RStudio IDE.

0. Create a New Repository

Although Git can also be used only on a local basis for most cases it makes sense to setup a remote repository. For private purposes, you can use one of these popular Git service providers:

  1. GitHub (by far the most popular one, recently bought by Microsoft).
  2. Bitbucket
  3. Gitlab

All providers support private and public repositories, even in their free plans.

Due to its popularity we describe account creation for GitHub only.

GitHub

  1. Create an account at GitHub: https://github.com/join.

{width=60%}

  1. Create a new Repository: https://github.com/new. You can select the package to be private if you don’t want others to see what you are doing. You can also initialize your package with a README.

{width=80%}

  1. Go to your repository URL (in e.g. https://github.com/username/mypackage) and copy the link of the Git repository. Use HTTPS to copy the

{width=80%}

1. Clone a Remote Repository

Next, we need to download our GitHub repository locally.

Using the command line we can use

git clone https://github.com/username/mypackage

This step creates a folder mypackage in the current working directory.

Within RStudio you can use the File | New Project dialog as described in Packages from Git Version Control in the section Creating Packages.

2. Change repository contents

The status of the git repository can be inspected using the command git status. Using RStudio you can also see the status of files in the Git tab.

{width=80%}

We would now like to create an R package within the newly created repository.

  • Create a new R-script file add.R including a function to add two vectors.
  • Additionally, modify the contents of README.md to describe the package contents (or at least the title for now).
  • Create a new empty file dummy.txt.

3. Commit changes

We now would like to add all changed files to the local repository. This requires two steps:

  1. Adding files to the staging area
  2. Committing files to the repository with a commit message.

We can do local commits as long as we want. This does not even require an internet connection. Only pushing the commits to a remote repository requires one (see next section).

Using the CLI, we can add files using git add. Too add all files from the current working directory to the staging area we can type:

git add .

We could also add only single files - like the changed README.md using

git add README.md

Next, we need to commit the files to the local Git repository. To accomplish this we use git commit. This opens the configured text editor on your local system and allows you to enter a commit message. Alternatively you can also use git commit -m "Your message" in which you can add a commit message within the command line. This is typically the quickest way to write one-line commit messages.

There are no strict rules for commit messages except that they must not be empty. However, recommend the following style guides for Git commit messages:

  • Uppercase the first letter of a commit message line. This makes the messages when presented in a list easier to read.
  • For longer messages use a header line to describe the message, leave the second line empty and put bullet points below of what has changed.
Major refactor of kernel API

- Fix issue #10: Implemented function for non-ASCII characters.
- Expand REST-API and refactor API function interface.
  • If using GitHub, use hash tags and references to issues, pull requests, etc. where possible, e.g.
Fixing #10: Bug for non-ASCII characters.

This not only closes the open issue #10 after a git push but also gives the user a link to the issue in question.

4. Push changes to the remote

{width=60%}

Once we are satisfied with our commits we can push them to the remote repository. This step is very important and should be done at least on a daily basis.

Using the command line you can use git push, or more explicitly

git push origin master

which pushes the branch master to the remote origin. Make sure you have configured your remote correctly using git remote -v and set the remote (if not already done) with

git remote set-url origin https://github.com/myrepo/project.git

In very specific cases you can also configure multiple remotes like upstream but we won’t need this setup right now.

If successful, we should see something similar like this:

$ git push origin master
Counting objects: 3, done.
Writing objects: 100% (3/3), 209 bytes | 209.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To https://github.com/Quantargo/mypackage.git
 * [new branch]      master -> master

RStudio

Within RStudio you can use the green Push arrow button to update the remote repository with your latest commit.

{width=60%}

5. Pull changes from the remote

To stay up-to-date with most recent changes at the remote repository we should constantly fetch and pull the latest changes. There are two commands which accomplish this: git fetch and git pull.

You can do a git fetch at any time to update your remote-tracking branches. This operation never changes any of your own local branches and is safe to do without changing your working copy. When you fetch, Git gathers any commits from the target branch that do not exist in your current branch and stores them in your local repository. However, it does not merge them with your current branch. This is particularly useful if you need to keep your repository up to date, but are working on something that might break if you update your files.

A git pull is what you would do to bring a local branch up-to-date with its remote version, while also updating your other remote-tracking branches. pull automatically merges the commits without letting you review them first. If you don’t closely manage your branches, you may run into frequent conflicts.

Git documentation: git pull:

In its default mode, git pull is shorthand for git fetch followed by git merge FETCH_HEAD.

To avoid frequent conflicts on your branches due to a unwanted merge operation from git pull we generally recommend you to run a frequent git fetch and run git pull only if your branch can be fast-forwarded (updated without conflicts).

RStudio

Within RStudio you can use the blue Pull arrow button to retrieve the latest commit from the remote repository.

{width=60%}

Exercise

  1. Visit your previously created GitHub repository at https://github.com/username/mypackage and select the initially created README.md file. Select Edit File, add a new line to README.md and save the file. The crucial point in this step is to make a change to any file outside your local Git repository.

{width=100%}

  1. You should now have created a new commit in the repository with the changed line in README.md.

{width=80%}

  1. Answer the Quiz questions after you have completed the previous 2 Steps: