13  Add, ignore, and commit files

🎯 Goal: In this chapter you’ll learn how to tell Git which files you’d like to track and which ones to ignore. Lastly, you’ll take your first “snapshot” (commit) of your project to send it to Github.

Caution

Before you get started on this chapter, please make sure you have enough time set aside to get through both this chapter and the next one. They build upon each other and we highly recommend you complete both in one sitting because it will be difficult to pick up where you left off later.

This is a good point to go take a break and eat a cookie 🍪 or drink some coffee ☕️ if you need to.

13.1 Ignoring files

In our last chapter, we ran the git status command to tell us what Git sees within our project.

Let’s take another look at those files.

  1. Run the following:

    git status

Under the “untracked files” sections, you should see a list of files in red like:

        .Rproj.user/
        .quarto/
        _quarto.yml
        my-first-git-project.Rproj
        my-first-git-project.html
        my-first-git-project.qmd
        my-first-git-project_files/

Currently, Git “sees” all the files in your working directory, including some files we may not actually want to include.

For example, notice those .html files in the list? HTML files are the rendered output from Quarto, and they change every time you make a change and click “Render” – something we tend to do a lot in our Quarto files.

Generally-speaking, we don’t save these kinds of rendered files in our repositories because they change so frequently and can cause a lot of headaches down the line, especially if we’re working with other people.

That said, there are some notable exceptions when you might include these files in Github:

  • If they’re small, essential, and need to be versioned for a specific reason.
  • If you’re outputting human-readable deliverables (like a PDF report or documentation site).
  • If you’re working on a static site or book.

For our purposes, we’ll be following the general best practice of excluding these kinds of rendered files – we’ll walk through how to do that below.

13.2 Introducing .gitignore

In a Git project, there are several types of files and directories that you typically want to keep out of our repositories to keep things clean, secure, and easy to manage.

What you ignore will depend on the type of project and the coding languages you’re using, but all Github projects use a file called .gitignore to let Git know what it shouldn’t be tracking in the project.

In general, the following kinds of files shouldn’t be tracked in Github:

  • Sensitive files: Files containing passwords or private information
  • Big files: Git isn’t built to keep track of large files.

For R and Quarto projects, this will include the following common file types:

  • Session and history files: .Rhistory, .RData, .Rproj.user/
  • Knitting files: .utf8.md, .knit.md
  • Output/render folders: *_files/ ,_site/, _book/
  • Editor and IDE Config Files: .Rproj.user/

Don’t worry if you don’t fully understand what all of these files are yet. The important thing here is to know is that there are things we should and should not upload to Github, and the way we keep the things we don’t want tracked out of our Github project is by using a .gitignore file.

We’ll set one up for our new project in the next step.

13.3 📝 Exercise: make a .gitignore

Let’s make a .gitignore file for your new Git project using the command line and the touch command.

  1. In the terminal, run:

    touch .gitignore

  2. In the RStudio Files pane, click on the new .gitignore file to open it.

    Tip: If you don’t see the .gitignore in your file pane, you may need to refresh by clicking the refresh icon at the top right of the file pane.

  3. In your blank .gitignore file, add the following lines and save the file:

    *.html 
_site/ 
.Rproj.user/

  4. Check your Git status again by running:

    git status

Remember when we ran git status before and we saw those .html files in our list of untracked files? Now the .html files should be gone from the list of files Git “sees” because we’ve told it to ignore these types of files with the *.html line in our ignore file.

Let’s quickly break down what each of these mean:

  • *.html : Ignore all .html files. (The * here tells Git “all files ending in .html”, regardless of their names)
  • _site/: Ignore the entire contents of the _site folder.
  • .Rproj.user/: Ignore the hidden RStudio files in the `.Rproj.user/ folder.

Before moving forward, let’s add a few more things to the .gitignore to cover some additional things we want to ignore (don’t worry about understanding what all of these are right now).

  1. Copy and paste the following code into your .gitignore file:

    # R
.Rhistory
.RData
.Rproj.user/

# Quarto
*.html
*_files/
*.utf8.md
*.knit.md
_site/
_book/

# System
.DS_Store

  2. Save and close the file.

  3. Run git status to preview the files git sees after the changes.

13.4 Staging: Adding the files you do want (git add)

Now that we’ve told Git what we don’t want to keep track of, we need to tell Git what we do want to track – in our case, the rest of our files. We’ll do that by using the git add command.

Let’s add our project files.

  1. Type the run the following command in your terminal:

    git add .
    • The . after the add means “add everything in this folder” (ignoring anything listed in .gitignore.)

  2. Now, check your project files by running git status again.

The output should look something like this now:

On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
        new file:   .gitignore
        new file:   _quarto.yml
        new file:   my-git-quarto-project.Rproj
        new file:   my-git-quarto-project.qmd

Notice that the heading has changed to “Changes to be committed” and files are now shown in green. The process you just went through is called Staging your files.

13.5 Committing: take your first Snapshot (git commit)

Now that you’ve told Git which files you care about, it’s time to take a “snapshot” of these files.

  1. Run the following in your command line:

    git commit -m "Initial commit: set up Quarto project"

Ok, so what did we just do?

  • Took a snapshot: We told Git “save a copy of the version of the files we just added” using the git commit command
  • Added a description of the snapshot: the -m is a flag that stands for “message”. The message describes the changes you made in your files, and every commit needs a commit message. The commit message is included inside a set of quotation marks.

We’ll talk more about commit messages in the next chapter, but for now know that they are a required and important part of the git workflow.

13.6 🎯 Checkpoint

In this chapter you:

  • Created a .gitignore file
  • Added the files you wanted to track (staged your files)
  • Took your first project snapshot (committed your files)

Great job! You’ve saved the first version of your project locally (AKA on your computer). Now, the snapshot needs to be saved to a remote project (AKA Github).

Next up

You’ll learn how to send this “snapshot” of our project by pushing our changes to Github for safe keeping.