Git Repository Structure and Workflow Stages

When learning Git, one of the most important things to understand is how a Git repository is organized, the workflow stages and how our work moves through different stages. Many beginners get confused by terms like working directory, staging area, repository or .git folder — but once these concepts are clear, Git becomes much easier to learn.

This guide explains everything in plain language, with examples that make sense even if you’re new to Git.

---

🧩 Prerequisites

Before exploring Git repositories and workflow stages, make sure you have:

• You have Git installed on your system
• You should be comfortable using a terminal or command prompt
• Git identity settings (user.name and user.email) are configures. They are not required for commands like git status or git add, but they are required when you make your first commit

If you have not yet installed Git or set up your identity for committing changes, refer to my detailed guide:
Installing and Setting Up Git on Windows, macOS, and Linux

This ensures that your git commit commands work properly.

---

📁 What Is a Git Repository?

A Git repository is a project folder managed by Git, where Git keeps track of our project’s files and remembers every change we make over time, allowing us to review, restore, and manage different versions of our project.

On hosted platforms like GitHub, we can create a new repository using the “Create repository” option (or a similar button). On a local machine, we can turn any normal folder into a Git repository by running the git init command, which creates a hidden .git folder that Git uses to track and store all changes.

Exercise 1:

Let us initialize a new repository locally. Create a folder git-demo-folder, open our terminal inside our project folder and run:

git init

This command converts our regular folder into a Git-powered project along with a hidden .git folder with full version-control capabilities.

---

🔍 Understanding the Three Git Workflow Stages

The local project folder where we have the hidden .git subfolder is called the working directory. This is the place where we actually create and edit our files.

On our local machine, not all files we create or modify are immediately tracked by Git. Every file goes through different stages — unstaged, staged, and committed — before becoming part of the tracked history.
Each stage plays an important role in helping us control what gets included, saved, and versioned in our repository.

Git’s workflow is typically represented as:

Unstaged (Working Directory) → Staged (Staging Area) → Committed (Repository)

This flow ensures that we have full control over what becomes part of our project’s version history, instead of Git tracking everything automatically.

Let’s look at each one using simple explanations.

---

1️⃣ Unstaged (Working Directory) — Where We Edit Our Actual Files

The working directory is our local project folder — the place where we create, edit, rename, and delete files. All changes begin here, and at this point they are considered unstaged because Git has not yet been told to track them.

What happens in the Working Directory?

• We edit existing files
• We create new files
• We delete or move files
• We update code or content

Example: If we open a file and add new code, that change exists only in the working directory.
Git notices the modification, but nothing is saved into version history yet.

Exercise 2: Checking the status of unstaged changes

Create a new file called newfile.txt, and add the text: “This is a new file.”

To see what Git detects in our working directory, run:

git status

This command shows:

• Untracked files → new files Git doesn’t know about yet
• Modified files → existing files that were changed
• Deleted files → files removed from the project

git status is our “dashboard” for understanding the current state of your working directory before staging or committing anything.
In our example, it will show newfile.txt as an untracked file.

---

2️⃣ Staged (Staging Area) — The “Preparation Zone” for Changes

The staging area is where we move selected changes when we want Git to include them in the next commit. Here, the changes are considered staged and ready to be saved.

How to stage changes

Stage one file:

git add <filename>

Stage all changes in the folder:

git add .

Simple Analogy

Think of the staging area like a shopping cart:

• We pick items (changes) we want
• We place them into the cart (staging area)
• At checkout (commit), all items in the cart get purchased (saved)

Why staging matters

The staging area gives you the ability to:

• Choose which changes to save
• Group related updates together
• Commit only what’s ready
• Avoid saving accidental or temporary modifications

Exercise 3: Checking the status of staged changes

Now let’s stage the file we created earlier using:

git add newfile.txt

To see how Git updates the file’s state after staging, run:

git status

This time the output will show:

• Changes to be committed → files that are staged and ready for commit
• The file name (e.g., newfile.txt) will appear in green
• Git is now aware that this file should be included in the next commit

git status helps confirm that your changes have successfully moved from unstaged to staged.

In our example, newfile.txt will now appear under “Changes to be committed”, indicating that it is staged and waiting to be committed.

---

3️⃣ Committed (Repository) — The Permanent Project History

When you commit staged changes, they become committed, meaning they are permanently recorded in your Git repository.
This saved history lives inside the hidden .git folder in your project.

What the Repository contains

• All commits (snapshots of your project over time)
• Branch information
• Tags and references
• Git metadata and configuration
• The complete version history of your project

⚠️ Important Note

If you delete the .git folder, you remove all Git tracking and project history.
Your project becomes just a normal folder again.

Example

When you run:

git commit -m "Add a new file"

Git saves your staged changes into the repository, making them part of the official project history.

Exercise 4: Checking the status after committing changes

Once a file is staged, we can save it permanently into our repository using:

git commit -m "Add newfile.txt"

After committing, we can run:

git status

This time the output will show:

• nothing to commit, working tree clean → meaning there are no pending changes
• No files listed under untracked, modified, or staged
• Your project is fully synced with the last commit

Git is telling us that the working directory, staging area, and repository are all aligned — everything is clean.

In our example, after committing newfile.txt, the file no longer appears as untracked or staged.
Instead, it has become part of the repository’s permanent history, and your working directory returns to a clean state.

💡 Note: If you have not set up user.email and user.name as discussed in the post Installing and Setting Up Git on Windows, macOS, and Linux, you may encounter an error similar to the one shown below.

---

🧠 Putting It All Together

Here’s the complete Git workflow:

Unstaged (Working Directory) → Staged (Staging Area) → Committed (Repository)

Workflow Explained

1️⃣ We make changes → They stay in the working directory (unstaged)
2️⃣ We prepare changes → We run git add to move them to the staging area
3️⃣ We save changes permanently → We run git commit to store them in the repository

This cycle repeats for every change we make, giving us full control over what is tracked, saved, and versioned.

---

🎨 Simple Real-Life Analogy

Think of writing a book:

• Working Directory:
  We are writing our draft on paper.
• Staging Area:
  We select which pages are ready to be added to the final book.
• Repository (.git):
  We save the selected pages into the published version.

This helps us track every version of our book.

---

📂 Summary: Untracked vs Tracked Files

Inside our working directory, files can be:

Untracked

Files Git is not monitoring yet.
(You need git add to start tracking them.)

Tracked

Files Git is monitoring and has seen before.

Tracked files can be:

• Modified (changed after the last commit)
• Staged (ready for commit)
• Committed (saved to the repository)

This is why running git status is so useful — it shows what Git knows about your files.

---

🎯 Final Thoughts

Understanding the Git repository structure gives clarity on:

• Why git add is needed
• Why commits save only staged changes
• How Git tracks your entire project
• Why the .git folder is so important

With these fundamentals, Git commands will make much more sense, and working with GitHub or Azure Repos becomes easier.

---

🎁 Bonus: Our Repository Is Still Local

At this point, everything we have done—creating files, checking status, staging changes, and committing—is happening only on our local machine. Our repository exists inside our project folder and is not yet shared anywhere else.

If we want our project to be available online, collaborate with others, or back it up, we will eventually need to push our local repository to a remote server such as:

• GitHub
• Azure Repos
• GitLab
• Bitbucket

We will explore how to connect our local repository to one of these providers and push our commits to a remote repository in an upcoming note when we introduce platforms like GitHub or Azure Repos.

For now, just remember:

All our work is currently stored locally. To share it or back it up, we will need a remote repository—something we will cover soon.