Tracking New Files — CleanCoDEDojo

Let’s add some files to our project folder that we can then track.

Creating or copying files in our repository

We can start by creating two essential files that every repository we eventually want to share with others should have: a README and a LICENSE.

The README

The README is the first thing anyone will see when they visit our repository. It covers basic aspects such as what the project is about, how to install or run it, or who it is meant for.

Having a minimal README is still better than having no README at all – we can start by adding a sentence or two that tells others (and our future selves) what this project is for, and refine it later on, as the project evolves.

For instance, we can use something like this as a starting point:

# Git Basics: Minimal Starter Project

This repository contains a minimal project structure with data, placeholder
analysis scripts, documentation, and tests demonstrating the local Git workflow,
from `git init` to the first commit and beyond.

The LICENSE

A LICENSE file tells others what they are allowed to do with our work. If we don’t include a license, the default is all rights reserved, meaning nobody can legally use, copy, or modify our work without permission. For starters, we can create an empty LICENSE file, which we can fill in later with the appropriate license text.

Our updated working directory structure now looks like this:

minimal-project/
├── .git/
├── README.md
└── LICENSE

Upon running the git status command again, we see Git has noticed the new files in the working tree: untracked files present. But Git will not version-control these files unless we explicitly tell it to, using git add.

> git status
On branch main

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
          LICENSE
          README.md

nothing added to commit but untracked files present (use "git add" to track)

Tracking new files in our repository

To begin tracking the README file, we can run git add README.md.

Running the git status command again, we notice that only our LICENSE file is still untracked:

> git status
On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
          new file:   README.md

Untracked files:
  (use "git add <file>..." to include in what will be committed)
          LICENSE

But while our README file is now being tracked, it isn’t stored safely in the repository’s history yet. Changes to be committed means the file is staged – Git will include it in the next commit, in the exact version it had when we ran git add README.md.

Git is also showing a helpful hint: use git rm --cached <file> to unstage. This works like an undo for staging: If we change our minds and want to exclude a file from the next commit, we can remove it from the staging area without deleting it from our working directory. The command essentially tells Git to stop tracking the file going forward.

The multipurpose command `git add`

Say we happen to notice a typo in our README and we haven’t committed the file yet. We edit the file to fix the typo, then run the git status command again:

> git status
On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
          new file:   README.md

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
          modified:   README.md

Untracked files:
  (use "git add <file>..." to include in what will be committed)
          LICENSE

Git notices a tracked file changed and lists this file under Changes not staged for commit. If we were to commit right now, this commit would store the previous version of the README before we changed it to fix the typo, instead of the updated version of the file as it now looks in our working directory.

To include the latest version in the next commit, we need to stage the updated version of the file by running git add README.md once more.

This is essential to remember: Staging with git add tells Git which changes you want to include in the next snapshot. This applies both to tracking new files like our README earlier and to staging updated versions of files that are already being tracked.

Git also shows another helpful hint: use git restore <file>... to discard changes in the working directory. You can run this command if you decide you want to discard the changes you have just made after all, and revert to the version Git currently knows about – in this case, the already staged version of the README.

Note: If you need to compare what changed, you can run git diff using appropriate flags and arguments to tell Git which versions to compare or customize how this is shown. The output shows which files are being compared and roughly where the changes are – some tools even let you jump straight there. For each change, you will see whether a line was removed (-), added (+), or modified (- shows the before and + the after versions). Surrounding unchanged lines are shown without any symbol for context.

Because we want to keep our fix, we stage it using the git add README.md command. Even though we edited our README file and staged the changes, Git will still show it as a new file until we make a commit, because there is no previous commit for Git to compare it against.

> git status
On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
          new file:   README.md

Untracked files:
  (use "git add <file>..." to include in what will be committed)
          LICENSE

Now that our README is staged, we are ready to make our first commit. We’ll explore this in detail in the next lesson.