3 Regular Project Workflow
These steps should be completed every day you work on the project. Although they may seem complex at first, once you get accustomed to them, you won’t need to think about it anymore.
Checklist ✅
- Add all the files you want to commit to the staging area.
- Create a commit message.
- Push the changes to the GitHub repository.
3.1 How to use the Git tab in RStudio
Git and GitHub were originally created for professional software development. It’s important to clarify that lab members are not expected to be expert users of Git and GitHub, but rather to handle basic commands necessary to achieve the use proposed.
Pay attention to the Git tab located in the top-right corner. Git will only display files that have been added, modified, or deleted since the project was initialized or since the last commit (we’ll cover what that means shortly).
Keep in mind that when we cloned the project from GitHub, two new files were added:
- The
.Rprojfile, created because we based our RStudio project on the repository.
- The
.gitignorefile, automatically generated as part of the project setup in RStudio.
These files will appear with a yellow question mark, indicating they are untracked—in other words, Git is aware of them but has not yet saved them under version control.
The README.md file initially did not appear in the Git tab. However, after adding the template and saving the changes, it now shows a blue “M,” which indicates that the file has been modified.
If you were to remove a file, you would see it next to a red ‘D’, indicating that it has been deleted from the project.
The next step is to save these changes in the project and add a descriptive title. Each time you save a new version of the project, we say you are making a commit, which you label with a title.
3.1.1 Add all the files you want to commit to the staging area.
The first thing you need to do is check in the Staged section of the Git tab all the changes you want to save under the same title. You will notice that sometimes a green ‘A’ appears. You can ignore this. The important part is that you check all the changes you want to save.
In our case, since we are working with non-collaborative repositories and the main purpose of using GitHub is to share data with other coworkers and maintain a backup. If at any point you need to learn more, at the end of this page, there are some recommended materials that might be helpful.
3.1.2 Create a commit message.
After doing this, you need to click the commit button to make these changes permanent in the project. You will then choose a message for the commit and click the Commit button.
How often should you commit?
Think of commits as checkpoints for related changes. If you might want to revert a set of changes later, commit them together.
3.2 Push the changes to the GitHub repository.
Finally, to push the changes to GitHub, click the Push button.
You’ll notice that the files in the Git tab disappear after you commit. This is expected, as Git only tracks changes between commits. Remember, if you don’t click the green arrow representing push, the changes will not take effect on GitHub.
If everything went smoothly, you should navigate to the repository URL and see the changes you made.
How often should you push?
Push your changes at least once a day after completing your work.
3.3 Moving foward with Git and GitHub 📚
If you want to learn more about Git and GitHub, we recommend the following books and tutorials:
Books
Happy Git and GitHub for the useR book (Bryan and Hester 2024)
Chapter 12 - Collaboration with version control from the book Data Science: A First Introduction (Timbers, Campbell, and Lee 2022)
The Turing Way Handbook: Git for research projects (The Turing Way Community 2023)
Tutorials
Software Carpentry: Version Control with Git (Gonzalez et al. 2019)
Setting up a GitHub Repository for Your Lab - Version Control and Code Management with GitHub (Our Coding Club)
Code Refinery - Introduction to version control with Git (CodeRefinery Project)