| English | 中文 |
A Git change-control handbook for AI-native software engineering: understand the design, verify changes, and manage collaboration.
AI can carry out operations. Understanding shapes the options we notice, the questions we ask, and the evidence we require before accepting a result. Without a concept in mind, we may never think to use it.
I maintain this handbook to explain enduring ideas in Git: how snapshots record state, how objects reuse content, how references organize history, and how collaboration handles divergence. These ideas support human judgment; AI helps us experiment, execute, and verify.
The emphasis shifts from execution fluency toward understanding, judgment, and verification. Practical skills still matter, especially reading critical commands and recognizing risk. Practice tests understanding.
Read the philosophy · Start learning interactively
Use the knowledge map to identify whether you are solving a conceptual question, one engineering change, or team collaboration before entering the articles below.
| What you want to develop | Start here | What you will be able to judge |
|---|---|---|
| Understand the design | Interactive learning → Learning path | Where changes live, how history forms, and what recovery depends on |
| Complete an engineering change | Accept a change end to end → Review example | Whether scope, commit revision, and test evidence agree |
| Manage collaboration | Team Git Workflow Guide → GitHub governance | How to isolate, review, authorize, release, and recover |
Git supplies versions and history. Tests, review, permissions, artifacts, and release systems complete change control. This handbook covers both the tool’s capabilities and their limits.
| Directory | Problems Solved |
|---|---|
| 01-getting-started | Git basics, mental models, and the knowledge map |
| 02-daily-workflow | Daily commands, branching and merging, rebase, stash, and worktree |
| 03-team-collaboration | Team workflows, PRs, Code Review, and selecting collaboration models |
| 04-github-engineering | Branch protection, Rulesets, CODEOWNERS, CI, releases, and security |
| 05-ai-native-development | Diff review, commit splitting, worktree, and multi-agent strategies for AI coding |
| 06-troubleshooting | Recovering from Git mishaps, conflict resolution, secret cleaning, and force push recovery |
| 07-large-repo | Large repositories, monorepos, partial clone, sparse checkout, and Git LFS |
| 08-templates | Templates for PRs, Issues, Reviews, Hotfixes, Releases, and AI Reviews |
| 10-company-practices | Enterprise engineering practice cases and decision maps |
Use animations, articles, and temporary-repository labs to understand Git snapshots, the object graph, references, history transformations, remotes, worktrees, and storage. The ten topics follow one sequence: 01 through 03 use the existing interactives and 04 through 10 use the added interactives. Material and scripts can be checked; reader understanding still needs prediction, reproduction, and transfer.
Open the Git Mental Model Interactive Lab
View the ten-topic article, interactive, and lab navigation
| The problem I’m facing | Suggested reading |
|---|---|
| Just committed to the wrong branch | Committed to Wrong Branch |
| Don’t know how to recover after reset, rebase, or force push | Git Troubleshooting Playbook |
| Team doesn’t know whether to choose GitHub Flow, Gitflow, or Trunk-Based Development | Team Git Workflow Guide |
| PR is too large, review is slow | Pull Request Best Practices |
| AI changed too many files at once, don’t know how to review | AI Change Review Examples |
| Large AI-generated diff needs to be split into commits or PRs | AI Commit Splitting, Stacked PR for AI-Generated Changes |
| Want to protect the main branch | Branch Protection |
| AI agents are pushing code and opening PRs, and I don’t know how to govern them | AI Agent Governance |
| Want an agent collaboration convention for the team repository | AGENTS.md Template |
| Too many PRs, main branch often broken after merge | Merge Queue |
| Clone, status, or checkout is slow in a large repository | Large Repository Git Practices |
| Want to directly copy team templates | Templates |
New content will prioritize official documentation and industry-standard materials:
For a more complete index of materials, see Recommended Reading.
See the roadmap for detailed plans.
The course, repairs, and collaboration material are collected in the v2.2.0 release notes and Changelog. The documentation was prepared on 2026-09-09; GitHub Releases records publication status.
Existing content will be gradually incorporated into new learning paths. See the legacy content migration for the migration list and the resources index for the materials index.
Original project content is licensed under the MIT License. Third-party materials, archived ebooks, external articles, linked resources, and quoted references remain under their original licenses and copyrights.
We welcome contributions of real-world problems, team practices, incident recovery experiences, AI programming workflows, and reusable templates.
Please follow the Content Style Guide for new content.