Commit changes

Overview

Teaching: 5 min
Exercises: 10 min

Questions

• How to describe the steps in a project?

Objectives

• Add and commit new code to the repository.

Add file and commit changes

In Git, changes are tracked by taking snapshots of the project folder, triggered by the user. A snapshot is taken by a commit, which is combined with a user defined commit message. It logs the username, date/time and defines the changes with the previous commit (added and removed lines/files).

Commit changes of a .gitignore file

In the previous episode, a .gitignore file was created, but this file itself is new and not yet part of version control. The status of the .gitignore file before the file is added to the Git history is clarified with the yellow question mark defining that the file is yet unknown to Git:

By checking the box and clicking commit, we add the file and are able to commit this addition with a commit message:

We get a small technical overview of the alterations we provided with this commit:

Add the gitignore file to the history

1. Go to git pane
2. Check the box next to .gitignore
3. Click Commit
4. Add a commit message and click commit
5. Click Close to remove the commit summary

Provide project info in README

It is good practice to commit often, so you will do this a lot. Each commit should only contain changes related to a single problem/element/… Each commit is a snapshot of your project and the messages describe the new steps taken in your project.

As documentation is crucial, providing some more information in the README.md file will help others (and yourself in a couple of months/years) to understand the aim of the project. Just as we adapted the README.md file online earlier, we can do the same locally.

Update the README.md of the project

1. Update the README.md inside Rstudio
2. Commit your changes in Rstudio

Project structure

During a project, new files are added to the project folder, which need to be version controlled as well. New directories and files can be added and committed, just as we did before.

Remark that we aim to have a clean directory structure in our projects with the data, scripts and output figures separated, for example:

|_ DCEcology
    |_ scripts
    |_ plots
    |_ data

By clicking the box next to a file, the file is staged (i.e. ready to be committed). Staging a new directory will stage all files in the directory. However, you can not stage empty directories!

Add data file to the project

1. Add the surveys.csv file in a new /data subdirectory
2. Describe the purpose of this file in the README.md
3. Commit both changes (new data file and the README.md adaptation) in a single commit message
4. Add and commit an R script as well, but put this into the scripts directory.

Create logical commits

As mentioned earlier, you should commit often and make sure each commit links to a specific change/problem. Sometimes, this means that you have to split the additions in a single file into two individual commits. Rstudio provides the interface to include specific lines of code into a commit message.

To summarize, the following actions can be executed:

• stage xyz: add the xyz from the commit
• unstage xyz: remove the xyz from the commit
• discard xyz: revert the changes in the xyz (be careful, can’t be undone!)

and xyz can be

• a single line
• a selection of lines
• a chunk
  • RStudio will automatically split the changes in chunks
  • Chunks are defined by 10 unchanged lines between changes

commit guidelines

Some guidelines to write nice commits:

1. Limit the subject message to 50 characters
2. Capitalize the subject message line
3. Do not end the subject message with a period
4. Use the imperative mood in the subject line
5. Use the body to explain what and why vs. how

Make logical commits

1. Make 2 unrelated changes to your R script
2. Create one commit for each change:
   1. Select the changes you want to commit and click stage selection
   2. Add a commit message and click Commit

Key Points

• A commit is a snapshot of the project with a user defined commit message

• Commit often!