# NOTE: renv initializing might need to be run twice after the repo is
# first copied.
#renv::init()
renv::restore()
suppressPackageStartupMessages({
library("dplyr") # For data manipulation
library("ggplot2") # For creating static visualizations
library("plotly") # For interactive plots
library("RColorBrewer") # Load Color Brewer color palettes
library("viridis") # Load the Viridis color pallet
})
# Function to select "Not In"
'%!in%' <- function(x,y)!('%in%'(x,y))Worked Through Example
asd
When I had to take Organic Chemistry in undergrad, my professor said that a successful student will learn why things are happening, as opposed to rote memorization. This very much applies for users of git as well. Memorizing specific scenarios you copy-and-paste code will only get you so far with git, as it will inevitably become a frustrating chore when things go wrong. And we’re talking about tech, we know things will go wrong at some point!
Unfortunately, we only have enough time to introduce you to the basic structures and workflows of git, today. I encourage you to read further about the different git commands and especially how information is moving through the git framework. You can start with some of the sources we’ve provided earlier in the workshop (Our Choice Resources) or some of the additional sources linked to below:
- “What is git commit, push, pull, log, aliases, fetch, config & clone” by Amit Prajapati
- “git Guides” by various Graphite contributors
- “How to Write a Git Commit Message” by cbeams
- git Graphical User Interface (GUI) Clients by various contributors
If you are beginner with git, be patient with yourself because this part takes time and practice, but as us Colorado skiers say “If there’s no pain 🎿, there’s no Jane 🗻!” Let’s get to it!
Basics of git/GitHub Interactions
In an established git version-controlled environment, there are three primary domains: the Working Tree, Staged Edits, and Committed Edits. The figure below exhibits how information moves through git’s version control and tracking framework on your local device. Notice the git * bash commands that drive the transitions between the three domains. For most scenarios, these are the git commands you will be using.
Let’s look at each version control domain our project files can be in:
The Working Tree is the area where the developer makes changes to files in the project. In this domain, git is not actively tracking changes that are made; changes get recycled back into the same file with no record of interim changes.
When you are ready for git to follow changes, you need to add them to the staged environment with
git add. This prompts git to identify differences between Staged Edits and already committed versions that are stored in the.gitdirectory.
Note
You will use the same commands even if there was no previous version of a file stored in the .git directory. When you check the version control status of your project with git status, git will automatically identify untracked files and prompt you to add them for tracking.
Code Like a Pro
git provides a robust framework to track changes within different files, including: storing comments explaining each change, tracing the file history, allowing recovery to older versions, and providing a line-by-line summary of changes from recent versions. Impressive!
Yet with all of this, git doesn’t directly track file name changes. (What?!) Instead, file name changes are detected with a heuristic comparing the similarity of files committed in .git to renamed files that have been staged. This is an important distinction to be aware of because sometimes git associates changes incorrectly.
Important
Moving a file within the git initiated environment is interpreted by git as a name change.
When committing a file name change, git deletes the file listed under the old name and replaces it with a new addition of the same file under the new name. The change history of a file leading up to a name change is always retained, but the transition between name changes are not explicitly tracked as such. It is therefore best practice to commit name changes with a message clearly stating this.
The git mv, for move or rename, command supports clearly recording file name transitions. Example from How to rename a file in Git by Kenny DuMez:
Command-Line Application
git mv oldfilename.txt newfilename.txt
git commit -m "Rename oldfilename.txt to newfilename.txt"- Once you have reviewed the detected changes and approve saving and sharing them, you use
git committo promote the staged version to become the most recent copy reflected in the.gitdirectory. It is the most recent Committed Edits that get synched over the GitHub server through a “peer-to-peer” patch.
A Simplified Example
Hopefully the explanations provided thus far are eliciting an aha moment for you. But if not, and you’re otherwise ready to pretend it makes perfect sense for a little longer, let’s go through an example. Later we are going to discuss version branches of your project. For now, all you need to know is we are in a git initialized project directory and on a version controlled branch called main.
April 22nd, 2025.
Imagine it. You have come up with what might be (and we’re scientists here so let’s not overstate) one of the best color schemes for your data ever. You generate this sweet looking, publication ready plot on the right and save the image as a file called earth_shattering_color_scheme.png. You’re now ready to record this version of your work and share it with the team through the projects GitHub (maybe even the world?), but the changes have not yet been recorded by git.
RECALL: The same steps are taken if this is your first image file for the plot or if you have tracked previous versions in the .git directory. For our example, it will be the former case.
It is always best practice to start by checking the current status of your version controlled project directory. Say that you generated this image using R in a script called making_cool_plots.R. Running git status in the command-line application will give you something like this:
Command-Line Output
On branch main
Your branch is up to date with 'origin/main'.
Changes not staged for commit:
(use "git add/rm
(use "git restore
modified: making_cool_plots.R
Untracked files:
(use "git add
earth_shattering_color_scheme.png
These outputs can be a little intimidating, so let’s break them down section-by-section.
The first statement is straight forward. git is letting us know that we are interacting with it in a version controlled branch called
main.origin/mainrefers to the remote GitHub repository version status of the same branch. “Origin” is an alias for the remote repository location. Equivalently, we can say something like:git@github.com:ysph-dsde/PROJECT-REPOSITORY.git/main.The output is telling us that our local copy of
mainis current with the last-checked status of the remote copy in GitHub. This means we don’t expect that there are local commits not yet reflected in the remote copy.
Note
Your local mirror of origin/main is not guaranteed to be a reflection of the remote repository contents in GitHub. Maybe you share the remote repository with a team who is actively pushing changes to the server, or maybe you changed a README.md, or uploaded a file directly in GitHub since you last synced your local copy. Your local git is not passively checking the status of the remote repository, so these changes will go undetected until we tell git to give GitHub a ring for a quick check-in.
It is therefore important to stipulate that origin/main in this context is the last checked status of the remote repository. Sometimes you might run into problems syncing locally committed changes with the remote repository because your local version of origin/main is not up to date.
It is best practice to commit file versions you want to retain to the local .git directory prior to updating your local mirror of origin/main. Later we will discuss the different commands git uses to pass information from the remote repository to your local mirrored copy.
The next section lists version tracked files stored in the
.gitdirectory that have been changed. git conveniently provides a few suggestions pointing to next steps:git add/rm/restore. Above, we see the color pallet changes we made in the already version controlled R script have been detected.The “untracked files” section is where files not previously tracked by git are listed. This means that no previously committed file versions have sufficient similarity with this file to be considered an updated version. Again, git provides us with a suggestion on the next steps:
git add.As expected, this is where our newly created image file is listed.
Up until this point, file iterations and changes are not recorded in git’s version history. Before we can store a snapshot of these edits, we need to first add them to the Staged Edits domain. This is done by using the git command git add in one of two ways:
Explicitly list out each file you want to add to Staged Edits OR
Use the “wild card”,
., to add every file listed under thegit statusoutput.
Command-Line Application
# OPTION #1: List each file
git add "making_cool_plots.R" "earth_shattering_color_scheme.png"
# OPTION #2: Use the wild card "." to add all files
git add .
# View the results of git add.
git statusCommand-Line Output
On branch main
Your branch is up to date with 'origin/main'.
Changes to be committed:
(use "git restore --staged
modified: making_cool_plots.R
new file: earth_shattering_color_scheme.png
The files have now been moved from the Working Tree to the Staged Edits domain. Notice that this domain is not applying any changes to your project directory. Merely, the stage is a buffer between pending changes and the codified version history of the projects contents. All files promoted for saving get packaged with a message explaining the reason for the version update.
Code Like a Pro
Astute students will notice that staging edits allows the opportunity to group like changes to one commit action. This is a highly advantageous feature that allows you to better control how version changes are recorded in .git. Doing so improves bug troubleshooting and minimizes collateral changes a revert might cause on unrelated parts of the project.
In our example, the two files we have staged are related and the changes we made are objectively flawless, so let’s proceed with committing the changes using git commit. Notice that a message is required with every commit action. It is easiest to add the message inline:
git commit -m "Revelatory message elucidating the hidden secrets of git."Because the message is a mandatory element of a commit action, if you forget to include one git will always be there to forcibly remind you by opening an editor where you can include one. Thank you so much, git. If you have not specified the editor git will use in such circumstances, then it will open up the default vi editor.
To show you how to navigate this outcome, we’re going to forget to include our message.
Command-Line Application
git commitCommand-Line Output
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit."
#
# On branch main
# Your branch is ahead of 'origin/main' by 1 commit.
# (use "git push" to publish your local commits)
#
# Changes to be committed:
# modified: making_cool_plots.R
# new file: earth_shattering_color_scheme.png
After entering git commit without a message, git automatically opens a vi window inside the command-line application. There are specific commands that you will need to use inside this application, some of which can be found here: “An introduction to the vi editor” by Ken Hess.
To add a message you need to do the following steps:
When the
viwindow first opens it is in “command” mode. Hit eitheraorion your keyboard to enter “insert” mode. When you do this, you might see-- INSERT --at the bottom of the application window.Add in your message in the line at the top of the document. Do NOT include a
#in front, as this will cause your message to be ignored.Hit
Escto exit “insert” mode and reenter “command” mode.Save progress typing
:wand hittingenter. If you are ready to exitvithen you save and exit using:wqinstead. NOTE::w/:wqwill show up at the bottom of the application window.
For our example, after I entered “insert” mode by typing a on the keyboard, I add the message “Outstanding progress on color schemes for density plot fill scaling.” I then save and exit vi by hitting Esc then typing :wq and hitting enter.
Command-Line Output
Outstanding progress on color schemes for density plot fill scaling.
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit."
#
# On branch main
# Your branch is ahead of 'origin/main' by 1 commit.
# (use "git push" to publish your local commits)
#
# Changes to be committed:
# modified: making_cool_plots.R
# new file: earth_shattering_color_scheme.png
:wq
Below the workflow overview is an example. Before staging the contents of the “main” branch in Git through git add, changes are not tracked, they are instead recycled into the main branch working copy. git add and commit will show the main branch is ahead of the origin/main copy. Origin, here, is the alias used to reference the remote repository and origin/main denotes the remote repository mirrored copied that is on the local device. Pushing these changes to the remote repository will cause the commit HEAD to merge with the main branch stored in the remote repository. HEAD is generally used to point to the latest commits in the checked-out branch.
