Basic Git Workflow
In this section we discuss a basic Git workflow which covers the following steps:
- Create a new Git(hub) repository
- Clone a remote repository.
- Change repository contents.
- Commit changes.
- Push changes to the remote.
- 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:
- GitHub (by far the most popular one, recently bought by Microsoft).
All providers support private and public repositories, even in their free plans.
Due to its popularity we describe account creation for GitHub only.
- Create an account at GitHub: https://github.com/join.
- 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.
- 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
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.
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
3. Commit changes
We now would like to add all changed files to the local repository. This requires two steps:
- Adding files to the staging area
- 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
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)
* [new branch] master -> master
Within RStudio you can use the green Push arrow button to update the remote repository with your latest commit.
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
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.
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).
Within RStudio you can use the blue Pull arrow button to retrieve the latest commit from the remote repository.
- 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.
- You should now have created a new commit in the repository with the changed line in
- Answer the Quiz questions after you have completed the previous 2 Steps: