Scope

This page outlines how users handle file changes in Git, covering the topics below and how the relevant actions can be executed via both the Command Line Interface (CLI) and the RStudio IDE:

• Git file state
• Staging files
• Committing changes
• Pushing

Git File State

From a tracking perspective, every file in your repository falls into 1 of 4 states:

• untracked - Git has never interacted with this file before and will not track any changes made to this file
• working directory - A file Git is already tracking was modified
• staging area - The modifications made to this file has been staged and will be bundled into the next commit.
• committed - Git has stored the changes to this file as a commit.

Git File State via CLI

To view the current state of any file in your repository, you can run:

git status

Git File State via RStudio

This can also be done in RStudio via the Git tab. Untracked files will appear with a yellow ? while tracked files that have been modified will appear as a blue M.

Staging Files

Once you are finished making changes, the next step is to add the modified/new files to the staging area so Git can track what to include in the next commit. This can be done in two ways.

Staging Files with CLI

git add <file_name>

This will add the specified file to the staging area. This command also offers some flexibility via pattern matching with a wild card so git add *.md will only stage files with the extension .md. git add . will additionally stage all files/folders in your current working directory.

Staging Files in RStudio

Staging files also be done in RStudio by clicking on the checkbox marked under the staged column. Untracked files will change from a yellow ? to a green A once staged.

Committing Changes

Once all your changes have been staged, the next step is to commit them to the Git repository.

A commit is a group of changes associated with a hash/timestamp that Git bundles together.

Commits are used to save changes locally and capture a snapshot of the project in its current state. These commits can then be pushed to the remote repository (described below).

The term HEAD is often used as a symbolic link to refer to the latest commit in the repository.

Files can be committed two ways.

Committing Changes via CLI

git commit -m <message>

The above command will commit the set of changes.

Committing Changes via RStudio

To Commit changes in RStudio

1. Press the Commit button
2. Type in a Commit message
3. Press Commit.

Commit Message

The commit message is the most important part of the commit. It lets other developers know what you were working on and what kind of changes are in the commit. This allows for easier evaluation and documentation in the review process for a set of changes.

Commit messages can be multiple lines. It is often good practice to include a very brief summary of changes on the first line, and then more details about the changes on subsequent lines. However, be wary of including too many unrelated changes in a single commit, as this hinders the evaluations and documentation mentioned above.

Conventional Commits

While it is often left up to the discretion of the group on whether any requirements around commit messages should be enforced, it is recommend you adopt a standard practice such as Conventional Commits. These commits involve commit message that preface themselves with a tag to hint at the kind of change.

For example instead of the message being changed function A to accept new input. It could be refactor: changed function A to accept new input. Tags could be anything such as:

• fix - Bug fixes
• da - data assembly
• model - add modeling related activities
• doc- Documentation updates
• refactor- Refactoring old code
• wip - Committing work in progress code
• feat - Adding a new feature

Pushing

After you have had a chance to make a commit (or several), it is time to push these changes to the remote repository so that all developers working on your project can access these changes.

Pushing via CLI

git push

The command above updates the remote repository with all the commits you have made locally.

Pushing via RStudio

In RStudio, after committing your desired files, you can push them by clicking the green up arrow in the RStudio Git tab.