Git: A Comprehensive Overview¶

This is the entry point to a set of git notes. It explains how git works and how the pieces fit together; the numbered documents go deep on each area and the git-adm tool automates the common flows.

Contents¶

1. What git is¶

Git is a distributed version control system. Every clone is a complete repository containing the full history, so almost every operation (commit, branch, log, diff) is local and fast, and you can work offline. A "central" server is a convention, not a requirement: it is just another repository that people agree to push to.

Three ideas explain most of git:

1. Snapshots, not diffs. A commit records the full state of the tree. Git computes differences when asked.
2. Everything is content-addressed. Objects are named by the hash of their content, so history is tamper-evident and identical content is stored once.
3. Branches are cheap pointers. A branch is a 41-byte file naming a commit. Creating one costs nothing, which is why branch-per-change workflows are practical.

Details: Internals.

2. The mental model: four places your work can live¶

 Working tree  ──git add──▶  Index (staging)  ──git commit──▶  Local repo  ──git push──▶  Remote
     ▲                            ▲                                 │  ▲                     │
     └──────git restore───────────┴─────────git reset / switch──────┘  └─────git fetch───────┘
                                                                          (git pull = fetch + merge/rebase)

Because the index sits between your files and the commit, you can build commits deliberately (git add -p), committing only part of your changes.

3. The object model in one page¶

• blob — file content. tree — a directory listing pointing to blobs and subtrees. commit — a tree + parent(s) + author/committer + message. tag — a named, optionally signed pointer.
• Commits form a directed acyclic graph (DAG). Each commit points back to its parent(s); a merge has two.
• Refs name commits: branches (refs/heads/*), remote-tracking branches (refs/remotes/origin/*), tags (refs/tags/*). HEAD says which branch (or commit) you are on.
• Rewriting history (amend, rebase, reset) never edits a commit; it creates new commits and moves a ref. The old ones linger until garbage-collected, which is why the reflog can rescue you.

        A ── B ── C ── D          main
                  \
                   E ── F         feature      (each letter is a commit; arrows point to parents)

4. Life of a change¶

git switch -c PROJ-1234-fix-login    # 1. branch from an up-to-date main
$EDITOR src/login.py                 # 2. edit the working tree
git status                           # 3. see what changed
git add -p                           # 4. stage the pieces you want
git commit -m "PROJ-1234 - Fix login redirect"   # 5. record a snapshot locally
git fetch origin && git rebase origin/main       # 6. replay onto the latest main
git push -u origin HEAD              # 7. publish; open a pull/merge request

Then review → merge on the host → delete the branch → git switch main && git pull. Full walk-through: Everyday workflow.

5. Branching and integrating work¶

Integrating one line of history into another can be done three ways:

Guidance: merge shared history, rebase private history. Never rebase what others have based work on. Deep dives: Rebase, Branch management.

Team workflows

• Trunk-based — very short branches, integrate to main daily, feature flags for unfinished work.
• GitHub/GitLab flow — feature branch → PR/MR → main (deployable). The default recommendation.
• Git Flow — long-lived develop, plus release/* and hotfix/*; suits scheduled, versioned releases.

See branching strategies.

6. Working with remotes¶

• git fetch downloads and updates remote-tracking refs; it never changes your branches.
• git pull = fetch + integrate. With pull.rebase=true it rebases your local commits on top of upstream.
• git push uploads commits and moves the remote branch; it is refused if it would discard remote commits.
• After rewriting pushed history use --force-with-lease, never plain --force.
• A branch's upstream is the remote branch it tracks; git status and git branch -vv show ahead/behind.
• Use SSH keys or a credential helper. Never embed tokens in remote URLs.

More: Repositories and remotes, Setup.

7. Reading history¶

git log --oneline --graph --decorate --all   # the shape of the DAG
git log -p -- <path>                         # a file's history with diffs
git log -S'text'                             # when did this string appear/disappear?
git blame <file>                             # who last changed each line
git diff A..B        git diff A...B          # tip-to-tip vs. since-they-forked
git show <sha>                               # a single commit
git bisect start / good / bad                # binary-search for a regression

8. Undoing things: a decision guide¶

Ask two questions: Is it committed? Is it pushed?

Full table, reset modes and common errors: Undo, recovery and troubleshooting. Setting work aside without committing: Stash.

9. Habits that prevent most git problems¶

1. Start every change on a new branch from an up-to-date main.
2. Make small, focused commits with imperative subjects ≤ 50 characters and a ticket key if your team uses one.
3. git status and git diff --cached before every commit.
4. Fetch/rebase often so conflicts stay small.
5. Prefer --force-with-lease; never force-push shared branches.
6. Stash or commit before switching branches, rebasing or resetting.
7. Enforce conventions with hooks and CI rather than memory.
8. Never commit secrets; if you do, rotate them first, clean history second.
9. Keep .gitignore current so build output and editor files stay out.
10. When something goes wrong, stop and read git status and git reflog before typing more commands.

10. Command map¶

11. The git-adm tool¶

git-adm wraps these workflows with prompts, dry-run and safety rails (it refuses destructive operations on main/master, stashes before discarding, uses --force-with-lease, and warns when you are behind the base branch). Source and usage: git-adm/README.md.

12. Glossary¶