beginner30 minby DevFox

Your First Repository and Commit

Build a real repository from scratch. The .git directory, the three areas, reading git status, staging with add and add -p, and writing commit messages worth keeping.

You have a folder with some files in it, and the only record of how it got that way is your memory. That works until the afternoon you change four things at once and one of them quietly breaks another.

By the end of this lesson you will have a real repository on disk called trip-planner, three commits inside it, and enough grip on the staging area to use it on purpose rather than by rote.

Turning a folder into a repository

Start with an ordinary folder. Nothing about it is special yet.

bash

mkdir trip-planner
cd trip-planner
ls -a

text

.  ..

Empty — ls -a shows hidden entries too, and there are none. Hand the folder to Git, then look again:

bash

git init
ls -a

text

Initialized empty Git repository in /home/you/trip-planner/.git/
.  ..  .git

One new thing appeared. A repository is not a folder Git watches from a distance; it is your files plus that hidden .git directory sitting next to them. Every commit, message, and past version of every file you ever save lives inside it. Your visible files are only the current view.

Running git init inside a folder that already has files is safe and extremely common. Git rewrites nothing; it only adds .git, and your existing files sit untracked until you add them. Run a Git command outside a repository and you get a message worth recognising on sight:

text

fatal: not a git repository (or any of the parent directories): .git

That almost always means you are in the wrong directory rather than that anything is broken. Check where you are and cd back in.

The three places a change can live

Get this picture straight before the first commit. The rest of Git is built on it, and almost every beginner's confusion is really a confusion about which of these three they are looking at.

Picture packing for a trip. Your things are all over the house. The suitcase on the bed holds only what you have decided is going. Zipping it shut and putting it in the car is a separate act again.

The working tree
Your folder as the editor sees it — the live files you are typing into right now. The whole house, mess included.
The staging area
Also called the index: the list of exactly what goes into your next commit. The open suitcase. Putting a shirt in it does not mean you have left yet.
The repository
The permanent history in .git. Committing zips the suitcase shut, labels it and stores it — recording what was inside, not what was strewn around the bedroom.

A file moves left to right, and each move is deliberate

What git status is telling you

Create the project's first three files:

Now ask Git what it sees. You will run git status more than any other command:

Read it line by line. On branch main is where you are. No commits yet means this repository has no history — true, you have committed nothing. Then the part that matters: all three files are untracked. Git can see them but has never been asked to record them, so it will not save or even notice changes to them.

Its headings map onto the three states a file can be in: untracked (never stored), modified (known to Git but different from the last commit, listed under "Changes not staged for commit"), and staged (in the suitcase, listed under "Changes to be committed").

The many faces of git add

git add is how things go into the suitcase. Three forms cover almost everything:

The last two are stated imprecisely almost everywhere. git add . stages new, modified, and deleted files under your current directory, so from a subfolder it skips changes elsewhere in the project. git add -A does the same across the whole repository, wherever you are standing. From the repository root they behave identically, which is why the difference is easy to miss until it bites.

Run git add README.md on its own and git status moves it under a new heading, "Changes to be committed", while the other two files stay untracked. That heading is the suitcase.

Your first commit

Stage all three files and take the snapshot:

0e3824e is the start of that commit's unique ID, and root-commit means it is the first, with nothing before it.

The -m flag supplies the commit message inline. Adopt the convention from day one: a subject of about fifty characters in the imperative mood, as if finishing the sentence "this commit will…". Add trip planner skeleton, not Added skeleton or skeleton stuff. Messages like update, fixes, and wip describe every commit ever written, and so describe none of them. A good subject tells a stranger — including you, in November — what they are looking at without opening the diff.

Change something, then read the status again

Add a sight to notes.md and a heading to README.md, then stage only the README:

Two headings, two different worlds. README.md is staged and will be in the next commit. notes.md is modified in the working tree only, and will not be unless you add it. The hints mention git restore, the modern command for undoing both — lesson 6's territory, so leave it for now.

The same state has a short format — dense, but fast to read once its two columns click. The left column is the staging area, the right is the working tree:

M — modified and staged; the M sits in the left column.
M — modified, not staged; note the leading space where the staging column would be.
MM — both. You staged a version, then kept editing, so the staged copy and the file on disk now differ. Committing saves the staged version, not what is on your screen.
?? — untracked, as all three files were a moment ago.

Stage the rest and make the second commit:

Staging half a file with git add -p

Here is the payoff for having a staging area at all. Turn pack.sh into a real script, and while you are at it jot a half-formed idea into notes.md. Instead of sweeping both up with git add -A, review the script change hunk by hunk:

Git walks you through the change one hunk at a time:

Press y to stage this hunk, n to skip it, s to split a big hunk into smaller ones, q to quit, and ? for the rest of the keys. Everything you say yes to lands in the staging area; everything else stays in your working tree, untouched, for a later commit.

Committing with the editor

Run git commit with no -m and Git opens your configured editor with an empty message and some commented help text. Write the message, save, close the file, and the commit is made; an empty message aborts it.

Do that now for the third commit. The shape is a short imperative subject, a blank line, then a body wrapped at about seventy-two characters:

Your notes.md scribble is still sitting unstaged in the working tree, exactly as intended. The blank line after the subject is not decoration: Git treats the first line as the subject wherever it shows a summary and the rest as the body, so dropping it turns the whole message into one long subject.

Reading the history with git log

Three commits in, ask to see them:

Newest first, with full IDs, author, date, and message. Long output opens in a pager — press q to get your prompt back. That one key traps almost everyone once.

For everyday use, the compressed view is better:

One line per commit: short ID, then subject. This is where fifty-character subjects earn their keep, and HEAD -> main marks where you are standing. Add --graph to draw the shape of the history down the left edge:

A straight line today, because you have one line of development. Once branches arrive that column forks and rejoins, and --graph earns its keep.

How often should you commit?

Commit whenever the project reaches a state you would be content to come back to: a working change, a finished paragraph, a test that passes. In practice that is several times an hour, not once a day. Small commits are easier to describe, to read later, and to undo one at a time, while a giant end-of-day commit called stuff is one opaque block you cannot pick apart. A useful instinct: if the subject line needs the word "and", you probably have two commits.

A cheat sheet to keep

Where to go next

You now have a repository with three commits and a working mental model: changes move from the working tree into the staging area into permanent history, and git status tells you where each one currently sits.

The obvious next question is what actually changed between those states — the contents, not only the filenames. That is the next lesson, reading what changed: git diff for unstaged edits, git diff --staged for what is in the suitcase, and git show for looking inside a commit you already made.

Before moving on, keep trip-planner and use it. Edit two files, stage one, read the status, commit it, then commit the other separately. Half a dozen rounds of that turns the three areas from a diagram you have read into something your hands know.