What problem it solves
The server config was edited yesterday, and today something broke. What exactly changed? Who changed it? How do you
get yesterday’s version back without losing today’s useful bits? Without history you’re left with traefik.yml.bak,
traefik.yml.old2 and memory.
Without git
config.yml.bak,config.yml.2026-10-17,config-working.yml- what changed — compare by eye
- why it’s like this — whoever edited it remembers, or nobody does
- the copy on the second computer drifts from the first
With git
- one file, the history of every version:
git log -p config.yml - what changed since this morning —
git diff HEAD@{8.hours.ago} - why — the commit message: “traefik: 60 s timeout — uploads were cut off”
- the copy on GitHub and on the server is the same history, synced with
pushandpull
How it works: three places and the path of an edit
an edit in the editor
- Working directory
git statusThe files as they are on disk. Git sees they differ from the last commit but does nothing with them. - Index
git addThe draft of the next commit. You put in it what goes into the commit — not necessarily every file, or even every line (git add -p). - Repository
git commitThe.gitdirectory: the snapshot from the index becomes a commit with an author, a date and a message. This is local — no network or GitHub needed. - Remote repository
git pushA copy of the history on GitHub or your own server.pushsends commits;fetchandpullbring in others’.
GitHub · origin/main
The index is what most other systems lack, and the main source of “why didn’t it get committed” questions.
git status always shows all three states: what’s in the index (Changes to be committed), what’s changed but not
added (Changes not staged), and new files (Untracked).
Commits and branches
a1b2c3 ── d4e5f6 ── 9f8e7d ← main, HEAD
└─── 7c6b5a ── 3e2d1c ← feature
- A commit is a snapshot of all files plus a link to its parent. Its name is a hash of the contents:
9f8e7d…. You can’t change a commit, only make a new one: the hash changes, and tampering shows. - A branch is a file holding one commit’s hash:
.git/refs/heads/main. A new commit moves the branch forward. Creating a branch means writing 41 bytes, which is why people make one per task. - HEAD is where you are now: usually it points to a branch. Pointing straight at a commit is
detached HEAD. - A merge joins two lines with a new commit that has two parents; a rebase moves one branch’s commits on top of another (Branches in git).
Commits no branch points to don’t vanish right away: git reflog remembers where HEAD has been, and git keeps such
commits for 30 days (gc.reflogExpireUnreachable). That’s why reset --hard and a botched rebase are almost always
reversible (Undo in git).
Where it’s used
Code
Any project, even a one-person one: history, branches for experiments, a copy on GitHub.
Server configs
/opt as a repository: edit on your computer, git pull on the server (Server configs in git).
Texts and sites
Markdown, MDX, documentation: this site is a repository, and every page is a file with its edit history.
Working with an AI agent
A commit before running the agent is a point to return to if you don’t like its edits (Clean git status before the agent).
Your own settings
~/.bashrc, ~/.ssh/config, ~/.gitconfig — in a dotfiles repository, the same on every machine. Keys and passwords —
never (A secret in a commit).
Other ways to solve it
Described from documentation as of October 2026; apart from git, none were run.
| How it works | How it differs from git | |
|---|---|---|
| Git | distributed: everyone has the full history | the standard: GitHub, GitLab, every editor and CI |
Jujutsu (jj) |
works on top of a git repository, compatible with GitHub | no index: the working copy is itself a commit; any action can be undone with jj undo; a conflict can be committed and resolved later |
| Mercurial | distributed, simpler commands | fewer tools and hosts; lives on in individual companies |
| Subversion | a central server; history lives only there | file locking, partial checkouts of directories, large binary files — that’s why game studios and designers keep it |
| Snapshots and backups | restic, provider snapshots | store copies, not history: no “who, why”, no branches or merges. Needed alongside git, not instead of it |
| If… | Use |
|---|---|
| code, configs, texts, working with others or with an AI agent | Git |
| you know git, but the index and complex rebases get in the way, and the repository is on GitHub | Jujutsu on top of the same repository |
| many large binary files, edited by one person at a time | Subversion or Git LFS |
| you need to restore a whole server after a disk failure | a backup; git is for the configs |
What you get and what it costs
What you get
- History is local.
log,diff,blameand commits work offline: all of history is in.git. - Branches cost nothing. An experiment lives in its own branch; if it fails, delete the branch, and
mainis untouched. - Almost everything is reversible. A commit you left via
resetor a rebase can be retrieved throughreflogfor another 30 days (Undo in git). - You see what changed.
git diffbefore committing is the last check that no stray file went into the commit. - One history everywhere. Computer, server and GitHub sync with
pushandpull, no copying folders around.
What it costs
- History remembers everything. A password that got into a commit stays in history even after the file is deleted.
After a
push, treat it as leaked and change it (A secret in a commit). - The commands are confusing.
checkoutdid five different things, which is why 2.23 addedswitchandrestore;resethas three modes,pullthree strategies. The settings in ~/.gitconfig block by block remove some surprises. - Rewritten history breaks things for others.
rebaseand--amendafter apushrequirepush --force, which wipes other people’s commits (push --force-with-lease instead of --force). - Large and binary files bloat the repository. Every version of a 50 MB image is another 50 MB in
.gitforever. - Windows changes line endings. Git for Windows turns LF into CRLF by default, and a script on the server breaks on
\r(Line endings in .gitattributes).
Where to start
- Git: what it is and how it stores history
- Git from scratch: the first repository and a push to GitHub over SSHInstall git, create a repository, make the first commit and push to GitHub with an SSH key.
- ~/.gitconfig block by block: what to set onceSettings worth setting once: a
mainbranch,pullwithout surprises, readable conflicts. - Everyday git: status, commits, branches, syncingEveryday commands: status, history, commits, branches, syncing.
- Branches in git: merge, rebase and conflicts step by stepMerge, rebase and conflicts: which to choose and how to resolve a conflict step by step.
- Undo in git: what happened — which commandWhat happened — which command: from an edit in a file to a deleted branch.
- Find where it broke: log, blame and bisect
log,blameandbisect: which commit broke it and why it was made. - Git and SSH keys: deploy keys, two accounts, signed commitsDeploy keys, two GitHub accounts on one computer, signing commits with an SSH key.
- Server configs in git: /opt as the repositoryServer configs in git:
/optas a repository, an allowlist and secrets kept out of history.
If it doesn’t work
fatal: not a git repository (or any of the parent directories): .git
- Cause
- The command ran outside a repository: there’s no
.gitin the current directory or above. - Fix
cdinto the project directory; for a new repository,git init(Git from scratch).
Author identity unknown *** Please tell me who you are.
- Cause
- Name and email aren’t set — no commit gets created without them.
- Fix
git config --global user.name "…"anduser.email(~/.gitconfig block by block).
! [rejected] main -> main (fetch first)
- Cause
- GitHub has commits you don’t: someone (or you, from another computer) pushed first.
- Fix
git pull, resolve conflicts if any, thengit push(Branches in git).
fatal: Need to specify how to reconcile divergent branches.
- Cause
- The branches diverged: there are commits both locally and on the server. Since git 2.33
pullwon’t choose the method itself. - Fix
- Once:
git config --global pull.rebase trueorpull.ff only(~/.gitconfig block by block).
You are in 'detached HEAD' state
- Cause
- You switched to a commit or tag, not a branch. New commits won’t land on any branch.
- Fix
- Just looking — go back with
git switch main. Made commits — save them as a branch withgit switch -c fix-x.
[email protected]: Permission denied (publickey).
- Cause
- GitHub didn’t recognize the key: it isn’t added to the account,
sshoffers a different key, or git runs a differentssh. - Fix
ssh -T [email protected]checks without git; keys and aliases — Git and SSH keys.