Your first repository

Why it matters

Reading about Git only goes so far; the commands become natural once you have used them a few times on a real folder. In this lesson you create a repository, learn the everyday loop (edit, status, add, commit), and learn to write commit messages your future self and teammates will thank you for.

Install and configure (once per computer)

Check whether Git is installed:

$ git --version
git version 2.47.0

If not: on macOS, running git --version offers to install the Command Line Developer Tools (or use Homebrew: brew install git); on Linux, use your package manager (sudo apt install git on Ubuntu or WSL); on Windows, Git for Windows (git-scm.com) includes Git Bash.

Tell Git who you are. This is recorded in every commit:

$ git config --global user.name "Your Name"
$ git config --global user.email "you@example.com"
$ git config --global init.defaultBranch main
$ git config --list

If you will push to GitHub and want to keep your email private, use the no-reply address GitHub shows in Settings > Emails.

Create a repository

Always create repositories in a project folder, never in your home folder:

$ mkdir -p ~/cli-practice/field-notes
$ cd ~/cli-practice/field-notes
$ git init
Initialized empty Git repository in /Users/alex/cli-practice/field-notes/.git/

The everyday loop

$ echo "# Field notes" > README.md
$ git status
On branch main
No commits yet
Untracked files:
  README.md
$ git add README.md
$ git status
Changes to be committed:
  new file:   README.md
$ git commit -m "Add README with project title"
[main (root-commit) 9e02c55] Add README with project title
 1 file changed, 1 insertion(+)

1. Edit files as usual.
2. git status shows what changed. Run it constantly; it also suggests next commands.
3. git add <file> stages a change (git add . stages everything in the current folder; check git status first).
4. git commit -m "message" records the staged snapshot.

Seeing what changed

$ echo "Site visit: river gauge read 1.42 m" >> notes.md
$ git diff              # unstaged changes, line by line
$ git add notes.md
$ git diff --staged     # what will go into the next commit
$ git log --oneline     # history, newest first

Press q if output opens in a pager.

Undoing before you commit

$ git restore notes.md            # discard unstaged edits to notes.md (cannot be undone)
$ git restore --staged notes.md   # unstage, but keep your edits

git restore on an edited file throws away those edits permanently, so check git diff first. (Older guides use git checkout -- file and git reset HEAD file for the same jobs; git restore needs Git 2.23 or newer.)

Writing good commit messages

A commit message explains what changed and, when it is not obvious, why.

• Start with a short summary, ideally under about 50 characters, in the imperative: "Add", "Fix", "Remove", "Update" ("Fix rounding in totals", not "fixed stuff").
• One logical change per commit. "Add README" and "Fix typo in report" are two commits, not one.
• If you need more detail, leave a blank line after the summary and write a short paragraph (use git commit without -m to open an editor).

Worked example: three meaningful commits

$ git log --oneline
c41d7a2 Add list of equipment to bring
5b8e310 Add notes from first site visit
9e02c55 Add README with project title

Each commit is small, has a clear message, and could be understood or undone on its own.

Common mistakes

• Running git init in your home folder, which makes Git track everything you own. If it happens, delete only that .git folder (rm -r ~/.git) after double-checking the path.
• git add . without checking git status, committing junk or secret files.
• Huge commits mixing unrelated changes.
• Forgetting to configure user.name and user.email.

Quick recap

• Configure Git once; create repos with git init in a project folder.
• Loop: edit, git status, git add, git commit -m.
• git diff, git diff --staged and git log --oneline show what changed.
• Small commits, imperative messages, one logical change each.

Try it

Open the Do tab to create your first repository.