Git 1d 🧩 The Git Workflow Local Repository 🧩 - KandZ

Git tracks every change to your project with fine-grained control. That control rests on one core idea: a file moves through three states — working directory, staging area, and local repository. Understanding these three states is the foundation of every Git command you’ll ever use.

This chapter covers the local workflow — no remotes, no collaboration, just you and your repository. It walks through the states, the essential commands, and a full worked example.

Understanding the Three States (The Git Lifecycle)

Every file in a Git repository lives in one of three states. Understanding the difference between them is what makes Git feel logical instead of mysterious.

Working Directory — where you actually edit files. Any tracked file you’ve changed is modified. Any new file Git doesn’t yet track is untracked.

Staging Area (Index) — a holding area for changes you’re preparing to commit. Only changes you explicitly git add are staged. It’s the draft of your next commit.

Local Repository — the .git directory. This is where permanent snapshots (commits) live. Once you git commit, changes are stored here forever.

┌──────────────────────────────────────────────┐
│                                              │
│  Working Directory                           │
│  (you edit here)                             │
│         │                                    │
│         │  git add                           │
│         ▼                                    │
│  Staging Area                                │
│  (index — the draft)                         │
│         │                                    │
│         │  git commit                        │
│         ▼                                    │
│  Local Repository                            │
│  (.git — permanent history)                  │
│                                              │
└──────────────────────────────────────────────┘

The working directory is your sandbox. You create files, edit them, delete them. Git watches but does nothing until you tell it to.

The staging area is Git’s distinctive feature. It lets you decide exactly what goes into the next commit — not everything you changed, but only the specific changes you select. You can split a day’s work into several meaningful commits, or leave half-finished experiments out.

The local repository is the archive. Every commit is a snapshot you can return to. Nothing is lost once it’s committed.

Why three states instead of two? Because precision matters. If every commit contained every change, you couldn’t separate “fix typo” from “add new feature.” The staging area gives you control over the shape of your history.

Basic Git Commands

These seven commands are the core of the local workflow.

`git init`

Purpose: Initialize a new repository in the current directory.

git init

Creates a hidden .git folder — the repository’s brain. Run this once per project.

`git add`

Purpose: Stage files for the next commit.

git add README.md      # stage one file
git add .              # stage everything in the current directory
git add src/           # stage a directory

Staging copies the current content into the index. If you edit the file afterward, the changes are not staged until you git add again.

`git commit`

Purpose: Save staged changes to the local repository.

git commit -m "Initial commit"   # short message
git commit                        # opens the editor for a longer message

Every commit records the author, timestamp, message, and a snapshot of the tree.

`git status`

Purpose: Show the current state — modified, staged, and untracked files.

git status

The most-used Git command. It tells you what’s changed, what’s staged, and what Git is ignoring.

`git log`

Purpose: Show commit history.

git log                     # full history
git log --oneline           # one line per commit
git log --graph --oneline   # visual branch graph

Useful options: --oneline, --graph, --decorate, -n N (limit), --author, --since.

`git restore`

Purpose: Revert changes in a specific file to the last committed version.

git restore README.md

Discards working-directory changes. This is destructive — the changes are gone.

`git restore --staged`

Purpose: Remove a file from the staging area without touching the working directory.

git restore --staged README.md

Unstages the file. Your changes stay in the working directory — you just take them out of the next commit.

`git commit --amend`

Purpose: Edit the last commit — change the message or add newly staged changes.

git commit --amend -m "Updated message"

Only amend commits that haven’t been pushed. Amending rewrites history — the commit hash changes.

Example: Simple Git Workflow

A complete walkthrough from empty directory to amended commit.

Step 1: Initialize a new repository

mkdir my-simple-project
cd my-simple-project
git init

You now have an empty repository. The .git folder exists but is hidden.

Step 2: Create and modify files

echo "# My Simple Project" > README.md
git status

Git reports README.md as untracked — it exists but Git isn’t tracking it yet.

Step 3: Stage and commit

git add README.md
git status

Now README.md is staged — ready to be committed.

git commit -m "Initial commit"
git status

Status reports a clean working tree. The commit is in the local repository.

git log --oneline

Shows one commit with its short hash and message.

Step 4: Modify and amend the last commit

echo "This is a simple project." >> README.md
git status

README.md shows as modified — the working directory has changes not yet staged.

git add README.md
git commit --amend -m "Initial commit with description"
git log --oneline

The previous commit is replaced by an amended one with the new content and a new message. Still one commit — now with more in it.

Step 5: Undoing changes

git restore README.md
git status

Discards working-directory changes — restores the file to its last committed state.

git restore --staged README.md

If the file had been staged, this unstages it — the changes stay in the working directory.

Do You Remember?

Test yourself on the fundamentals.

How do you initialize a new Git repository?
How do you stage all changes in your working directory?
How do you stage specific files?
How do you commit staged changes with a message?
How do you open an editor to write a longer commit message?
How do you check the current state of your repository?
How do you view a concise list of commits?
How do you discard changes in the working directory for a specific file?
How do you modify the last commit message or add more changes to it?

If you can answer all nine, you understand the local workflow.

Complete Example Session

# ============================================
# PART 1: INITIALIZE
# ============================================

mkdir my-simple-project
cd my-simple-project
git init
# [ Initialized empty Git repository in /path/to/my-simple-project/.git/ ]

# ============================================
# PART 2: FIRST FILE
# ============================================

echo "# My Simple Project" > README.md

git status
# [ On branch main ]
# [ No commits yet ]
# [ Untracked files: ]
# [     README.md ]
# [ nothing added to commit but untracked files present ]

# ============================================
# PART 3: STAGE
# ============================================

git add README.md

git status
# [ On branch main ]
# [ No commits yet ]
# [ Changes to be committed: ]
# [     new file:   README.md ]

# ============================================
# PART 4: COMMIT
# ============================================

git commit -m "Initial commit"
# [ [main (root-commit) a1b2c3d] Initial commit ]
# [  1 file changed, 1 insertion(+) ]
# [  create mode 100644 README.md ]

git status
# [ On branch main ]
# [ nothing to commit, working tree clean ]

git log --oneline
# [ a1b2c3d (HEAD -> main) Initial commit ]

# ============================================
# PART 5: MODIFY
# ============================================

echo "This is a simple project." >> README.md

git status
# [ On branch main ]
# [ Changes not staged for commit: ]
# [     modified:   README.md ]

# ============================================
# PART 6: STAGE AND AMEND
# ============================================

git add README.md

git commit --amend -m "Initial commit with description"
# [ [main e4f5g6h] Initial commit with description ]
# [  1 file changed, 2 insertions(+) ]

git log --oneline
# [ e4f5g6h (HEAD -> main) Initial commit with description ]
# (same commit, new hash, new message, more content)

# ============================================
# PART 7: RESTORE (DISCARD CHANGES)
# ============================================

echo "extra change" >> README.md

git status
# [ modified:   README.md ]

git restore README.md

git status
# [ nothing to commit, working tree clean ]

# ============================================
# PART 8: RESTORE --STAGED
# ============================================

echo "staged change" >> README.md
git add README.md

git status
# [ Changes to be committed: ]
# [     modified:   README.md ]

git restore --staged README.md

git status
# [ Changes not staged for commit: ]
# [     modified:   README.md ]
# (unstaged, but the change is still in the working directory)

Quick Reference

The Three States

State	Where	What
Working Directory	Your files	Untracked / modified
Staging Area	Index	Staged
Local Repository	`.git`	Committed

Core Commands

Command	Purpose
`git init`	Create a new repository
`git add FILE`	Stage a file
`git add .`	Stage all changes
`git commit -m "msg"`	Commit with message
`git commit`	Commit with editor
`git status`	Show current state
`git log`	Show history
`git restore FILE`	Discard working changes
`git restore --staged FILE`	Unstage a file
`git commit --amend`	Edit last commit

Useful `git log` Options

Option	Effect
`--oneline`	One line per commit
`--graph`	Visual branch graph
`--decorate`	Show branch/tag names
`-n N`	Show only N commits
`--author=NAME`	Filter by author
`--since=DATE`	Filter by date

State Transitions

From	To	Command
Untracked	Staged	`git add`
Modified	Staged	`git add`
Staged	Committed	`git commit`
Modified	Committed state	`git restore`
Staged	Modified	`git restore --staged`

Amending vs Committing

Action	Command
New commit	`git commit -m "msg"`
Change last commit message	`git commit --amend -m "msg"`
Add changes to last commit	`git add .` then `git commit --amend`
Undo last commit, keep changes	`git reset --soft HEAD~1`

Best Practices

✅ Do This:

# Check status often
git status                                       # ✅

# Use clear commit messages
git commit -m "Fix login redirect bug"           # ✅

# Stage intentionally
git add specific-file.js                         # ✅

# Commit small, focused changes
# One logical change per commit                  # ✅

# Amend only unpushed commits
git commit --amend -m "Better message"           # ✅

# Use --oneline for quick history
git log --oneline                                # ✅

# Discard working changes only when sure
git restore file.js                              # ✅

❌ Don’t Do This:

# Don't amend pushed commits
git commit --amend                               # ❌ rewrites public history

# Don't git add . blindly
git add .                                        # ⚠️  may include secrets

# Don't write vague commit messages
git commit -m "stuff"                            # ❌

# Don't use git restore to undo commits
git restore file.js                              # ⚠️  only for working changes

# Don't stage a file and then edit it
# (edit is not staged until re-add)              # ⚠️

# Don't confuse restore and reset
git restore --staged file.js                     # ✅ unstages
git reset --hard                                 # ❌ discards everything

# Don't commit huge binary files
git add video.mp4                                # ⚠️  use Git LFS

Common Pitfalls

Pitfall	Problem	Solution
Forgot to `git add`	Nothing to commit	Stage first
Edited after staging	Changes not in commit	Re-`git add`
`git restore` on staged	Only works on working tree	Use `--staged`
Amended a pushed commit	History rewritten	Never amend pushed
Vague commit message	History is useless	Be specific
`git add .` added junk	Committed secrets	Use `.gitignore`
Confused `restore` and `reset`	Different scopes	`restore` = working/staged, `reset` = commits

Real-World Examples

1. Initialize a project

mkdir app && cd app && git init

Creates the .git folder.

2. Check status

git status

Shows modified, staged, untracked.

3. Stage one file

git add README.md

Adds it to the index.

4. Stage everything

git add .

Stages all changes in the current directory.

5. Commit with message

git commit -m "Add README"

Records a snapshot.

6. Commit with editor

git commit

Opens the configured editor for a longer message.

7. View history

git log --oneline

Compact log.

8. Discard working changes

git restore file.js

Reverts to last commit.

9. Unstage a file

git restore --staged file.js

Removes from index, keeps changes.

10. Amend last commit

git commit --amend -m "Better message"

Replaces the last commit.

Visual: The Three-State Lifecycle

┌──────────────────────────────────────────────┐
│  Working Directory                           │
│                                              │
│  ┌──────────────┐                            │
│  │ Untracked    │                            │
│  └──────┬───────┘                            │
│         │                                    │
│  ┌──────┴───────┐                            │
│  │ Modified     │                            │
│  └──────┬───────┘                            │
│         │                                    │
│         │  git add                           │
│         ▼                                    │
│  ┌──────────────────────┐                    │
│  │  Staging Area        │                    │
│  │  (staged)            │                    │
│  └──────┬───────────────┘                    │
│         │                                    │
│         │  git commit                        │
│         ▼                                    │
│  ┌──────────────────────┐                    │
│  │  Local Repository    │                    │
│  │  (committed)         │                    │
│  └──────────────────────┘                    │
│                                              │
└──────────────────────────────────────────────┘

Visual: `git restore` vs `git restore --staged`

┌──────────────────────────────────────────────┐
│  git restore FILE                            │
│                                              │
│  Working Directory ──► Last Commit           │
│                                              │
│  Discards working-directory changes          │
│  Staged changes are unaffected               │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  git restore --staged FILE                   │
│                                              │
│  Staging Area ──► Working Directory          │
│                                              │
│  Unstages the file                           │
│  Working-directory changes remain            │
│                                              │
└──────────────────────────────────────────────┘

Visual: A Typical Workflow

┌──────────────────────────────────────────────┐
│  1. Edit files in working directory          │
│                                              │
│  2. git status → see what's changed          │
│                                              │
│  3. git add FILE → stage intentionally       │
│                                              │
│  4. git status → verify what's staged        │
│                                              │
│  5. git commit -m "message" → save snapshot  │
│                                              │
│  6. git log --oneline → review history       │
│                                              │
└──────────────────────────────────────────────┘

Visual: Amending a Commit

┌──────────────────────────────────────────────┐
│  Before amend                                │
│                                              │
│  A ──► B ──► C  (HEAD)                       │
│                                              │
│  After git commit --amend                    │
│                                              │
│  A ──► B ──► C'  (HEAD, new hash)            │
│                                              │
│  C is replaced — not added as a new commit   │
│  ⚠️  Never amend a pushed commit             │
│                                              │
└──────────────────────────────────────────────┘

Summary

Concept	Meaning
Working Directory	Where you edit files
Staging Area	Holding area for the next commit
Local Repository	`.git` — permanent history
`git init`	Create a repository
`git add`	Stage changes
`git commit`	Save a snapshot
`git status`	See current state
`git log`	View history
`git restore`	Discard working changes
`git restore --staged`	Unstage a file
`git commit --amend`	Edit the last commit

Key takeaways:

Every file moves through three states — working, staged, committed
The staging area gives you precision — you decide what goes in each commit
git init creates the repository once
git add stages changes — repeat after any further edit
git commit saves the staged snapshot permanently
git status is your dashboard — run it often
git log --oneline gives a compact history
git restore discards working changes — destructive
git restore --staged unstages but keeps changes
git commit --amend rewrites the last commit — never on pushed commits
Commit small, focused, meaningful changes with clear messages
Never git add . blindly — check what you’re staging

Remember: The local workflow is the foundation. Initialize once, edit in the working directory, stage deliberately, commit permanently. Use git status constantly. Amend only unpushed commits. Master these three states and the seven commands that move between them, and the rest of Git — branches, merges, remotes — builds on solid ground.

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!