A Safe First Git Workflow: Inspect, Stage, Review, Commit

You will turn an existing directory into a small, inspectable Git history: initialise a repository, see what Git noticed, stage only the intended file, review the staged patch, and create one commit. The commands use Git 2.43.0, the version installed on the machine used for this guide. Allow about 10 minutes for a first run.

Before you start

You need a shell, Git, and a directory containing files you are willing to track. Replace /path/to/project with that directory. You do not need elevated privileges for this workflow. Do not run these commands in a directory that already contains a repository unless you have checked its history first: git init can reinitialise an existing repository, but that does not make it a clean starting point.

Check the installed version and confirm the target directory exists:

git --version
test -d /path/to/project && echo "directory exists"

On the reference system, the first command prints:

git version 2.43.0

1. Enter the project

Change directory before asking Git about files. Git normally discovers a repository by looking in the current directory and its parents, so running a command from the wrong place is an easy way to inspect a different project.

cd /path/to/project
pwd

Checkpoint: pwd must show the project directory you meant to edit.

2. Create the local repository metadata

Initialise the directory:

git init

Git creates a .git directory containing the repository metadata. The working files remain where they were. A normal result includes a line similar to Initialized empty Git repository in .../.git/; the exact path and branch name may differ.

Verify that Git now recognises the directory:

git rev-parse --show-toplevel
git status --short

The first command prints the project root. The second lists untracked files with ??, or prints nothing if the directory has no eligible files. Git status is deliberately short here: it is easy to scan and safe to repeat.

3. Inspect before staging

List the files Git sees as untracked:

git status --short --untracked-files=all

Do not treat the list as an instruction to add everything. Check for secrets, generated output, caches, private keys, and large temporary files first. A .gitignore file can prevent known unwanted paths from appearing, but it does not remove a file that was already staged or committed.

For a new repository there is no commit to compare against, so git diff is empty until something is staged. That is normal. Choose one harmless file for this first commit, such as README.md.

4. Stage one deliberate path

Stage only the chosen file:

git add -- README.md

The -- separates options from the path. It is useful when a filename begins with a hyphen, and it makes the command's boundary clear. Replace README.md with a real path in your project. Do not use git add . for this first check unless you have inspected every untracked path.

Checkpoint: confirm exactly what is staged:

git status --short
git diff --cached --name-status

A staged new README appears as A README.md in status, and as A README.md in the name-status output. If an unexpected path appears, remove it from the index without deleting its working file:

git restore --staged -- path/to/unwanted-file

5. Read the exact staged patch

Review what the commit would contain:

git diff --cached -- README.md

For a new text file, the patch shows each added line with a leading +. Stop here if the content includes credentials or anything that should not be shared. Editing the working file after staging does not silently update the staged snapshot, which is why this review matters.

After editing, repeat the cycle. Run git diff -- README.md to see unstaged edits, then run git add -- README.md again and review git diff --cached. Git keeps the index, the proposed next snapshot, separate from the working tree.

6. Make the first commit

Commit only after the staged patch is correct:

git commit -m "Add project README"

Git records the staged snapshot and opens no editor when -m supplies the message. The command needs an author identity. If Git reports that it cannot auto-detect your identity, configure it deliberately rather than copying an identity you do not control:

git config --global user.name "Example User"
git config --global user.email "[email protected]"

Those commands change your user-level Git configuration. Omit --global if you want the identity only in this repository. Re-run the commit after checking the staged patch again.

7. Verify the recorded history

Check the latest commit and the working tree:

git log -1 --oneline
git status --short

The log prints a short object ID followed by your commit message. A clean working tree produces no output from the second command. For a more explicit summary, use:

git show --stat --oneline HEAD

Checkpoint: the file listed in the commit is the file you reviewed, and git status --short is empty or contains only changes you intentionally left for later.

Common traps and safe recovery

Git says this is not a repository. You are probably outside the intended tree, or the directory has not been initialised. Run pwd, then git rev-parse --show-toplevel. Do not set GIT_DIR casually: it overrides the usual .git discovery and can point commands at a different repository.

Status is empty but files are present. Files may be ignored, or you may be in a nested path whose parent repository is handling them. Use git status --ignored --short to inspect ignored paths. Do not force-add a secret merely to make it visible.

You staged the wrong file. Use git restore --staged -- path. This changes only the index; it does not delete the working file. Avoid git reset --hard while learning this workflow. It can discard tracked working-tree changes, so it is not a routine undo command.

The commit message or content is wrong. Before sharing the repository, amend only after reviewing the replacement staged snapshot: git commit --amend -m "Correct message". Once a commit has been pushed or supplied to other people, prefer a new corrective commit rather than rewriting shared history.

Done means

• git --version reports the installed Git version you expected.
• git status --short shows no accidental staged paths.
• git diff --cached was reviewed before committing.
• git log -1 --oneline shows the intended commit.
• You know how to unstage a path with git restore --staged -- path, without deleting its working file.