Understanding the Git Workflow: Working Directory, Staging, Commit and Push

Joe — Sun, 23 Aug 2026 02:58:05 +0000

Working through a practical reference to moving a change through Git took me through the process of taking a single change from my local computer, committing it in Git, and pushing it to GitHub where others would be able to see it. This was written for complete Git Novices and so I approached it without any prior experience of using Git.

By the end, you will be able to move a change through all four Git stages and confirm it's visible on GitHub with a clear commit history.

Who This Is For

Anyone that want to work with Git in the terminal
Users who find git add, git commit, and git push unclear
No prior Git experience required

Prerequisites

Git installed (git --version to check)
A terminal or command-line application
A GitHub account (create one if needed)

We'll use a small sales data project as a running example. You do not need Python or Pandas installeda as we will be only tracking files, not running code.

The Four-Stage Flow

Every change travels in one direction:

Project Directory → Staging Area → Local Git Repository → Remote Github Repository

Project directory: where everything is worked on
Staging area: choosing what goes in
Local Git Repository(Commit): your historical record for everything worked on
Remote Github Repository(Push): share it so collaborators can see it

Setup: Initialize a Repository

Create a project folder and make it a Git repository:

mkdir monthly-sales
cd monthly-sales
git init

Expected output:

Initialized empty Git repository in /path/to/monthly-sales/.git/

git init creates a hidden .git folder where Git stores the entire history. From now on, Git watches this folder.

Usage

1. Working Directory (Untracked Files)

Create a raw data file:

echo "date,region,revenue" > sales_data.csv
echo "2026-01-01,East,1200" >> sales_data.csv

Check its status:

git status

Expected output:

On branch main
No commits yet
Untracked files:
  (use "git add <file>..." to include in what will be committed)
        sales_data.csv

Untracked means Git can see the file but isn't following it yet. This is the default for new files.

2. Staging Area (Choose What to Commit)

Stage the file:

git add sales_data.csv
git status

Expected output:

On branch main
No commits yet
Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
        new file:   sales_data.csv

The label changes from Untracked files to Changes to be committed. The file is staged but not yet saved to history.

PRO TIP

If you edit two unrelated files (e.g., raw data and a cleaning script), you don't have to commit them together. Stage and commit one, then come back for the other. This keeps your history readable.

NOTE

git add . stages everything at once.
Always run git status first so you know exactly what that includes.

3. Commit (Local Snapshot)

Create a commit:

git commit -m "Add raw January sales data"

View the history:

git log

Expected output:

commit 6f3a1e2c9d8b4a17f0e3c5d9a2b1e8f7c3d4a5b6
Author: Some Rando <somerando@example.com>
Date:   Sat Aug 22 10:15:03 2026 +0000

    Add raw January sales data

A commit is a permanent snapshot of everything staged, saved with a message, timestamp, and author details. It's local until you push.Commit messages have two readers: your future self and collaborators.

PRO TIP

Writing Good Commit Messages:

Use the imperative mood ("Add", "Fix", "Update")

Say specifically what changed

Explain why when it isn't obvious

Cover one logical change

Weak	Strong
update	Add February revenue row to raw sales data
fix	Fix currency parsing for negative revenue values
changes	Drop rows with missing region before export
wipe	Add first draft of sales cleaning script

For longer commit messages, run git commit without -m to open your editor. Use a short summary line, a blank line, then a detailed body:

Fix currency parsing for negative revenue values

Regions reporting refunds submit revenue as "-120.00", which the
previous parser rejected as invalid. This adds a check for a
leading minus sign before the numeric conversion.

Demonstration: Separate Commits for Separate Changes

Make two changes—one to an existing file and one new file:

echo "2026-01-02,West,950" >> sales_data.csv
echo "import pandas as pd" > clean_sales.py
echo "df = pd.read_csv('sales_data.csv')" >> clean_sales.py
echo "df.to_csv('clean_sales.csv', index=False)" >> clean_sales.py

Check status:

git status

Expected output:

Changes not staged for commit:
        modified:   sales_data.csv

Untracked files:
        clean_sales.py

Stage and commit them separately:

git add sales_data.csv
git commit -m "Add February revenue row to raw sales data"

git add clean_sales.py
git commit -m "Add script to clean and export sales data"

git log

git log now shows three commits, each describing one specific change.

4. Push (GitHub)

Connect your local repository to an empty GitHub repository:

git remote add origin https://github.com/your-username/monthly-sales.git

Push:

git push -u origin main

Expected output:

Enumerating objects: 9, done.
Writing objects: 100% (9/9), done.
To https://github.com/your-username/monthly-sales.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

origin is the nickname for your GitHub URL.
main is the branch being pushed.
-u links your local main to origin/main, so future pushes can just be git push.

Verify on GitHub:

sales_data.csv and clean_sales.py are present
The commit history shows three separate, clearly labeled commits
Locally, git status reports nothing to commit (working tree clean)

That's the success signal: a local change, visible on GitHub, with a history that explains itself.

Troubleshooting

Symptom	Cause and Fix
`git commit` runs, but GitHub shows nothing	Commits are local only. Run `git push` to upload.
`nothing to commit, working tree clean`	Changes must be staged. Run `git add <file>`, then `git status`.
`git add .` staged files you didn't want	Run `git status` first. Use a `.gitignore` to exclude secrets, `.env`, etc.
Secrets committed by mistake	Treat them as compromised and rotate. Removing them later doesn't erase history.
`fatal: No configured push destination`	No remote is set. Run `git remote add origin <url>` before pushing.
Vague commit messages ("update", "fix stuff")	Not an error, but unreadable history. Follow the commit message guidelines.

Quick Reference

Stage	Command	Result
Working Directory	create/edit a file	Untracked or modified
Staging Area	`git add <file>`	"Changes to be committed"
Local Repository	`git commit -m "msg"`	Permanent local snapshot
Remote Repository	`git push`	Visible on GitHub

When in doubt, always run:

git status

Try It Yourself

In a new, empty folder:

Repeat all four stages with a data file or script of your own.
Edit two unrelated files in the same session.
Stage and commit them as two separate commits, each with a specific, imperative-mood message.
Run git log and confirm each commit describes exactly one change clearly enough that a teammate wouldn't need to ask what it means.

DEV Community: Joe

Understanding the Git Workflow: Working Directory, Staging, Commit and Push

Who This Is For

Prerequisites

The Four-Stage Flow

Setup: Initialize a Repository

Usage

Try It Yourself