Git Repository
Create a repository, inspect each state transition, and stage exact files so the proposed snapshot is reviewable.
A repository is a tracked project
Preflight: know where the repository will live
git init acts on the current directory unless you give it another path. Before running it, print the current location and list the directory. Initializing your home folder, desktop, or a parent containing many projects can make unrelated files appear in one repository.
# macOS, Linux, or Git Bash
pwd
ls -la
# Windows PowerShell
Get-Location
Get-ChildItem -ForceCreate a small practice folder
Use a disposable project with no secrets, dependencies, or generated output. Pick the command block matching your shell, or create the folder and README in your editor.
Shell setup
mkdir hello-history
cd hello-history
printf "# Hello History\n" > README.md
printf "Purpose: learn one Git transition at a time.\n" >> README.mdPowerShell setup
New-Item -ItemType Directory hello-history
Set-Location hello-history
Set-Content README.md "# Hello History"
Add-Content README.md "Purpose: learn one Git transition at a time."Read the README before continuing. Git records bytes, not your intention to have saved them. An unsaved editor buffer is not in the working tree.
Initialize the repository
From inside hello-history, run git init. Git creates a hidden .git directory containing repository configuration, references, the index when needed, and the object database.
git init
git rev-parse --show-toplevel
git statusgit init
Creates or reinitializes repository metadata. It does not stage, commit, or publish project files.
rev-parse --show-toplevel
Prints the repository root Git discovered from the current directory.
git status
Explains the current branch, commit state, index changes, working changes, and untracked paths.
.git
Holds repository identity and history. Do not edit or delete it as ordinary project clutter.
The first status should say there are no commits yet and show README.md as untracked. That is success: the working file exists, but the index does not yet select it.
Test what you learned
Which command prints the root directory of the repository Git currently discovered?
Read status as a report, not a ritual
Status is organized advice derived from the three-place model. Read all of it:
- 01Where am I in history?
Before the root commit, the branch has no commits. Later, status names the current branch.
- 02What is staged?
“Changes to be committed” describes index entries that differ from HEAD.
- 03What is unstaged?
“Changes not staged for commit” describes tracked working content differing from the index.
- 04What is untracked?
These working paths have no index entry and will not enter the commit until selected.
Status also suggests commands, but suggestions are not instructions to run blindly. First decide which state you intend to create.
Stage one exact path
Use the narrowest clear pathspec for the first snapshot:
git add README.md
git status
git diff --cachedgit add README.md reads the current README content, creates or reuses its blob, and updates the index entry. It does not remember to include every future edit. The second status should move README from “untracked” to “changes to be committed.”
add updates the proposal—it does not upload
STEP WORKING TREE INDEX HEAD
after file creation README v1 no entry no commit
after git add README v1 README v1 no commit
after git commit README v1 README v1 README v1
after editing again README v2 README v1 README v1The command name is historical and sometimes misleading. git add handles new files, modified files, and selected deletions by updating the index to match content from the working tree. It does not add a file “to GitHub,” and it does not create history by itself.
git add README.md
Updates one named path in the index from the current working tree.
git add src/
Updates matching changes under one directory. Review the result before committing.
git add -A
Updates additions, modifications, and deletions across the repository. Broad and deliberate—not a beginner default.
git add -p
Interactively selects change hunks. Powerful when one file contains multiple intentions; covered later in practice.
Review the exact proposed commit
Before committing, ask two different questions:
git diff --cached
- Shows index versus HEAD.
- For a root commit, compares against no parent snapshot.
- Should show the README you intend.
- Answers what the commit will change.
git diff
- Shows working tree versus index.
- May be empty immediately after staging.
- Reveals edits made after
git add. - Does not include untracked file content.
An empty plain diff after staging is not evidence that work vanished. It means the working tree currently matches the index. The cached diff is now the relevant review.
Test what you learned
Which command previews index changes that the next commit will record?
The next lesson, Git Commit, records this reviewed index as history. Stay here until you can explain every path in git status.
Know when not to run git init
Use git init when a local project has no Git history and you intend to begin one. If a remote repository already contains commits you need, clone it instead. Cloning creates a local repository, downloads history, configures a remote, and checks out a working tree.
Troubleshoot the first workflow
Author identity unknown
Inspect user.name and user.email with origin and scope, then set the intended configuration.
Nothing to commit
The index matches HEAD. Check whether the file was saved, ignored, already committed, or never staged.
Too many untracked files
You likely initialized the wrong root. Print the top-level path before staging anything.
Expected file missing
Read status and confirm spelling, path, save state, and ignore rules. Do not compensate with a broad add.
Independent lab: a reviewable staged snapshot
Create a disposable folder named first-snapshot-lab. Add two files: README.md describing the project and notes.txt with one learning goal. Then:
- Prove the current directory before initialization.
- Initialize the repository and record the reported root path.
- Use status to explain both untracked files.
- Stage only
README.mdand provenotes.txtremains untracked. - Review the cached diff. Do not commit yet—that is the next lesson.
Common repository mistakes
Initializing the wrong folder
Verify location and repository root before any broad staging command.
Using git add . reflexively
Stage paths that belong to one coherent snapshot, then inspect the cached diff.
Assuming add uploads to GitHub
git add updates the local index. No remote has been contacted.
Trusting status suggestions blindly
Read the report, then choose the next state on purpose.
Lesson review
You created a repository deliberately, used status to observe each transition, staged an exact file, and reviewed the index. The next lesson records that proposal as a commit.
- I verify the project folder and repository root before staging anything.
- I know that
git initcreates metadata but does not commit working files. - I stage exact paths and review
git diff --cachedbefore committing. - I know
git addis a Git command, not a GitHub upload.