The Three States

Jan 22, 2024 · 4 min read · git ·

Making sure you remember that we are talking about a local git repository here.
That's right, that .git invisible directory, right inside your project directory.
(this post if part of the material I cover in my devops course)

Locations

Consider this cli listing:

1$> 
2$> pwd
3/home/osboxes/my-project
4$> ls -la
5total 12
6drwxrwxr-x  3 osboxes osboxes 4096 Jan 22 11:24 .
7drwxr-x--- 32 osboxes osboxes 4096 Jan 22 11:46 ..
8drwxrwxr-x  7 osboxes osboxes 4096 Jan 22 11:51 .git
9$>

As you can see, I am in my project directory.
This directory (and all subdirectories of it) are called the working directory (or sometimes the working tree).
there is a single .git directory here. This is the git repository.
Git will track files in this area (dir and subdirs), but only if I tell it to.
You can see that this is the working directory by trying this:

1$> git status
2On branch master
3
4No commits yet
5
6nothing to commit (create/copy files and use "git add" to track)
7$>

If you try this in other places:

1$> 
2$> pwd
3/home/osboxes/my-project
4$> cd ..
5$> git status
6fatal: not a git repository (or any of the parent directories): .git
7$>

Making a first commit

As you can see, there are no text files in the working directory yet.
Let's create a new file there, then try git status again:

 1$> 
 2$> echo hello > file1
 3$> ls -la
 4total 16
 5drwxrwxr-x  3 osboxes osboxes 4096 Jan 23 02:07 .
 6drwxr-x--- 32 osboxes osboxes 4096 Jan 22 11:46 ..
 7-rw-rw-r--  1 osboxes osboxes    6 Jan 23 02:07 file1
 8drwxrwxr-x  7 osboxes osboxes 4096 Jan 23 02:01 .git
 9$> 
10$> git status
11On branch master
12
13No commits yet
14
15Untracked files:
16  (use "git add <file>..." to include in what will be committed)
17	file1
18
19nothing added to commit but untracked files present (use "git add" to track)
20$>

We can see that git tells us that there is a file that git does not track yet.
That means that the file is not kept inside the .git (this is the repository) yet.

The staging area

Before doing anything else, I'm adding another file (whatever text content) called file2
Here's what git says now:

 1$> 
 2$> git status
 3On branch master
 4
 5No commits yet
 6
 7Untracked files:
 8  (use "git add <file>..." to include in what will be committed)
 9	file1
10	file2
11
12nothing added to commit but untracked files present (use "git add" to track)
13$>

I'd like to commit to this changes, but I'm not sure about file2, it is just file1 I want to save now.
This is what the staging area is all about.

The staging area is actually like a stage:

You put your actors (files you want to save) on the stage.
You do that by using git add command
Then you commit your changes by using git commit
Only those files that were staged before, are commited.

 1$> 
 2$> git add file1
 3$> git status
 4On branch master
 5
 6No commits yet
 7
 8Changes to be committed:
 9  (use "git rm --cached <file>..." to unstage)
10    new file:   file1
11
12Untracked files:
13  (use "git add <file>..." to include in what will be committed)
14    file2
15
16$> git commit -m "this is my first commit"
17Author identity unknown
18
19*** Please tell me who you are.
20
21Run
22
23  git config --global user.email "you@example.com"
24  git config --global user.name "Your Name"
25
26to set your account's default identity.
27Omit --global to set the identity only in this repository.
28
29fatal: unable to auto-detect email address (got 'osboxes@osboxes.(none)')
30$>

Wait..what just happened?
Ahh..git does not know who is it that commits some changes now.

Basic Configuration

In the last section git was suggesting that we configure user.emil and user.name
Git suggestion was to configure that as global, so that configuration would work in all local repositories.
I'd configure that locally:

1$> 
2$> git config user.email "yuval.shaul@gmail.com"
3$> git config user.name "Yuval Shaul"
4$>

I now try to commit again:

1$> git commit -m "this is my first commit"
2[master (root-commit) 696c35e] this is my first commit
3 1 file changed, 1 insertion(+)
4 create mode 100644 file1
5$>

The 3 states

So, every file or change of file starts in the working directory
You then stage it (using git add command), but only what you really want to save in this commit
You then commit
This can be summarized in the following diagram (from the git site):