basforge

Search titles, text and the “If it doesn’t work” cases.

    RU
    OverviewDevelopmentGit

    Git: what it is and how it stores history

    Git stores a directory’s history as snapshots: every commit is the full state of the files, a link to the previous one, and a note on who and why. A branch is a name pointing at a commit, so branches cost nothing, and almost any action can be undone. A copy on GitHub is the same history, not a separate program.

    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 push and pull

    How it works: three places and the path of an edit

    an edit in the editor

    1. Working directorygit statusThe files as they are on disk. Git sees they differ from the last commit but does nothing with them.
    2. Indexgit 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).
    3. Repositorygit commitThe .git directory: the snapshot from the index becomes a commit with an author, a date and a message. This is local — no network or GitHub needed.
    4. Remote repositorygit pushA copy of the history on GitHub or your own server. push sends commits; fetch and pull bring 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

    The main case

    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.

    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, blame and 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 main is untouched.
    • Almost everything is reversible. A commit you left via reset or a rebase can be retrieved through reflog for another 30 days (Undo in git).
    • You see what changed. git diff before committing is the last check that no stray file went into the commit.
    • One history everywhere. Computer, server and GitHub sync with push and pull, 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. checkout did five different things, which is why 2.23 added switch and restore; reset has three modes, pull three strategies. The settings in ~/.gitconfig block by block remove some surprises.
    • Rewritten history breaks things for others. rebase and --amend after a push require push --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 .git forever.
    • 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

    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 .git in the current directory or above.
    Fix
    cd into 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 "…" and user.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, then git 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 pull won’t choose the method itself.
    Fix
    Once: git config --global pull.rebase true or pull.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 with git switch -c fix-x.

    [email protected]: Permission denied (publickey).

    Cause
    GitHub didn’t recognize the key: it isn’t added to the account, ssh offers a different key, or git runs a different ssh.
    Fix
    ssh -T [email protected] checks without git; keys and aliases — Git and SSH keys.