Git Operational Notes

This repository contains a set of notes I’ve compiled while working with Git across different projects and teams.

Rather than documenting every possible command, the focus here is on the patterns that tend to matter most in real engineering work: keeping history readable, structuring branches sensibly, recovering work safely, and reducing friction when collaborating with others.

If you already know the basic Git commands but want to develop more reliable habits around version control, you may find these notes useful.

I did not put this repository together as a command reference or a quick cheat sheet. The intention was to create something closer to a working reference — a place I can return to when building features, reviewing code, investigating problems, or tidying up history before merging a branch.

The material is organised into three levels:

• Foundation track — core Git behaviour, first commits, and branching fundamentals
• Working track — collaboration practices, remote workflows, and maintaining clean history
• Deep track — rebasing, recovery strategies, release handling, and commit-level investigation

The goal is to make Git usage more deliberate. Knowing the commands is useful, but understanding the judgement behind them matters far more.

---

Repository Structure

Foundation track

For engineers who want a steady starting point.

1. foundation/01-first-steps.md
2. foundation/02-staging-with-intent.md
3. foundation/03-branching-in-practice.md
4. foundation/04-correcting-slip-ups.md

Working track

For engineers who already use Git regularly and want cleaner habits.

1. working/01-shaping-history.md
2. working/02-handling-remotes.md
3. working/03-collaboration-rhythm.md
4. working/04-ignore-tags-stash.md

Deep track

For situations where more control and deeper understanding are needed.

1. deep/01-rebase-pick-reset.md
2. deep/02-release-routines.md
3. deep/03-investigating-with-git.md
4. deep/04-recovery-notes.md

---

Operating Principles

The workflows described here are guided by a few simple ideas:

• prefer clarity over cleverness
• keep commits small enough to review comfortably
• treat commit history as an engineering asset
• avoid rewriting shared history without a clear reason
• optimise for long-term maintainability rather than short-term speed

---

Why I kept these notes

After using Git across different projects, I realised the difficult part is rarely remembering a command.

The real challenge is keeping the history understandable for the next person who reads it — including your future self.

That is why these notes focus more on judgement than syntax:

• when to split changes into several commits
• when rebasing makes more sense than merging
• when rewriting history is acceptable
• how to recover calmly when something goes wrong
• how to keep pull requests easier to review

---

Common Failure Modes

A few Git problems appear repeatedly in team environments:

• oversized pull requests that are difficult to review
• vague commit messages that make history harder to interpret
• long-lived branches drifting too far from main
• careless force pushes on shared branches
• panic-driven resets before checking the reflog

Most Git issues are recoverable, but they are far easier to resolve when the workflow is disciplined from the start.

---

A workflow I use frequently

git switch main
git pull origin main
git switch -c feature/improve-input-validation

git add .
git commit -m "feat: tighten validation for empty customer records"

git push -u origin feature/improve-input-validation

Maintained by Ami

• GitLab Certified Git Associate
• GitLab user since 2016