This post assumes you have Git set up in an RStudio project and that you have a basic idea what Git is for. If not, start back at the post Time to Grow Up and Use Git. Once you have an RStudio project set up with Git support, come back here.
First note that in the toolbar under your menu bar there’s a new icon that looks a bit like an astrology symbol but that actually says Git sideways:
We’ll call that the Git Icon Menu. In addition, RStudio’s Environment-History pane will have a new tab labelled Git that looks like this:
We’ll call this the Git Pane. If you click certain buttons in the Git Pane or select certain options in the Git Icon Menu, a window titled RStudio: Review Changes will open. I’ll call this the Git Window. The Git Window has different looks depending on how you open it, but there’s really just one window, as we’ll see in a moment.
With three exceptions, everything else in the Git Icon Menu is also in the Git Window and is more naturally used from there. With two exceptions, everything else in the Git Pane is also in the Git Window and, again, is more naturally used from there. In other words, this post will focus on the Git Window.
One of the Git Icon Menu exceptions, the Project Setup… choice, is a duplicate of Project Options… in the Tools menu. The other two exceptions are the selections that open the current file on GitHub in either the standard view or the blame view (blame view shows a file’s current code by which version of the file each line originated in). You can’t do any of those things from the Git Window.
One of the Git Pane exceptions, the Shell… choice in the More dropdown menu, opens a terminal window external to RStudio. I much prefer Tools > Terminal > New Terminal, which does the same thing, but as an additional tab in RStudio’s Console Pane. The other exception is the New Branch button at the right end of the Git Pane. There’s nothing that will do that in the Git Window. I’ll discuss what New Branch does later.
The Git Window looks like this when the Changes button in its upper-left corner is depressed (from the Git Icon Menu, you get this look by selecting either Diff or Commit…; likewise, from the Git Pane, you get this look by clicking either the Diff or Commit buttons):
If the History button that’s next to the Changes button is depressed (or the Log or History choices in the Git Icon Menu are selected or the History button in the Git Pane is clicked), the Git Window looks like this:
When you change a file in your project and save it, the file’s name will appear in the Changes version of the Git Window. If you click on the name to select the file, you can review the changes you’ve made in the bottom part of the window.
Changes always incorporate entire lines, so, as in this example, a change to a line will delete what the line looked like previously (red lines) and add what it looks like now (green lines). But realize that if you are working on a document that has paragraphs of text that “soft wrap” at the right edge of the window, Git will consider the entire paragraph to be a single changed line.
Changes will also be chunked. Gray bars divide the chunks and each chunk begins and ends with unchanged code. The Context dropdown in the Changes version of the Git Window (but not in the History version), will let you control how many lines of unchanged code are shown. There is also a checkbox for hiding blank lines in the code.
At the top of the Changes version of the Git Window you can click on the Stage, Revert, or Ignore buttons. Revert will remove all the shown changes from the file and save it. Those changes will be gone forever. Ignore will add the file’s name to a list of files you never want to see in this list again. Stage will check the box in front of the filename, which you can also check by clicking on the box.
After that box is checked, you can click the Commit button to make the changes in this file part of the current version of the project. A single commit can include changes to several files. Just check the boxes next to the files you want to include in the commit. However, note that only the changes in the selected file show up in the bottom part of the window; and they show up whether you’ve you checked its box or not. Only the staged files (the ones with checked boxes) will be included in the commit.
But wait. Before you click the Commit button, use the Commit Message box to explain what this change is about. A recommended format for this is a short headline, a blank line, and a more complete description of the change. The headline you use will identify the commit when you look through the version history. For example, in the History version of the Git Window above, the words Add Demo Link came from the headline of a commit.
If the same headline appears several times in the version History, it means the commit included several files. You can see everything that was in a previous version of a file by selecting its commit and then clicking the View File @ text on the right, just above the area where the commit’s changes are shown. This gives you a chance to see, copy, or save the entire file as it previously existed.
If you are the only one updating your project and you also click the Push button after every commit, your project’s files on GitHub will stay in sync with the ones on your own computer. However, if there are others who are also updating the project on GitHub, you should click Pull first to grab any changes others have made, then click Push. If you and someone else have both changed the same line of code, you’ll get a message that basically says you’ll have to fix that before proceeding.
You can also wait to Push until after several commits. In this case, the version History will show the last commit that has been pushed with purple markers. In the version History Git Window shown above, there have been no commits since the last push, so the purple markers are on the top line.