🟢 GitHub Mini-Playbook: 10 Mistakes I Won't Repeat
A guide from one developer to another on navigating version control without the headaches.
The principles of managing code collaboratively are universal, but whether you're using a large monorepo or a small project on GitHub, the learning curve can be steep.
I’ve mentored many new programmers, and I see the same patterns—the same mistakes I made when I started. I’ve nuked branches, leaked credentials, and created merge conflicts so complex they required a whiteboard and three cups of coffee to untangle.
Getting comfortable with Git and GitHub isn't just about memorizing commands; it’s about building a workflow that keeps you, your code, and your team safe and efficient.
Let’s dive into my personal playbook of the top 10 mistakes I’ve made and the concrete actions I now take to avoid them.
📜1. A Messy, Unreadable Commit History
The Mistake
Making giant, vague commits like git commit -m "progress" or lumping dozens of unrelated changes (a bug fix, a new feature, a typo correction) into a single monster commit.
The Playbook: Treat Commits like Checkpoints, Not Save Files
Core Principle: A commit should be a single, logical, atomic unit of change.
Commit Often: Commit every 15-30 minutes. Small, frequent commits are easy to understand and revert.
Commit One Idea at a Time: If you fix a bug and refactor a function, make two separate commits.
Use the Staging Area Intelligently: Use git add -p to stage changes chunk by chunk, splitting one file into multiple commits.
Write Clear, Standardized Commit Messages: Use prefixes like feat:, fix:, docs:. Explain the *why*, not just the *what*.
“Write diary notes daily, not novels once a year.”
🌿2. Branching Gone Wild
The Mistake
Creating a branch and then working on it for weeks. These "mega-branches" diverge so far from main that merging them becomes a nightmare of resolving conflicts.
The Playbook: Branches are for Sprints, Not Marathons
Keep Branches Short-Lived (1–3 days): If a task is bigger, break it into smaller sub-tasks and smaller branches.
Merge Quickly: Once tested and reviewed, merge your branch. Don't let it sit idle.
Delete Branches After Merging: Keep the repository clean. Use git branch -d feature-name.
“Don’t keep doodle pages lying around; paste them back into your notebook fast.”
🤯3. Fear of Conflicts
The Mistake
Avoiding `git pull` for days because you're scared of merge conflicts. This only makes the eventual conflict larger and more complex.
The Playbook: Resolve Conflicts Early and Often
Pull Daily (or More): Start every day with git pull --rebase origin main. This downloads the latest changes and replays your local commits on top.
Resolve Small Conflicts Immediately: A 3-line conflict is easy to fix. A 300-line conflict is a recipe for introducing new bugs.
Communicate: If you and a teammate are working in the same file, talk to each other! A quick chat can prevent hours of frustrating conflict resolution.
“Erase pencil smudges daily, don’t wait for the whole notebook to get messy.”
🕹️ Merge Conflict Playground
$ Ready to practice resolving a merge conflict!
👤4. Unclear Ownership
The Mistake
A Pull Request (PR) sits for days with no reviewer, or a critical bug is found and no one knows who the expert on that part of the code is.
The Playbook: Assign Everything Clearly
Assign Issues and PRs: Every Issue and PR should have a clear assignee who is responsible for driving it to completion.
Use CODEOWNERS file: For critical parts of the codebase, define owners in a `CODEOWNERS` file. GitHub will automatically request reviews from them on any PR that touches those files.
Require at Least One Approver: Configure branch protection rules to require at least one approving review before a PR can be merged.
“Every homework page must have one student’s name on top.”
✅5. Skipping or Rushing Code Reviews
The Mistake
Pushing directly to `main` to bypass review, or getting a "LGTM" (Looks Good To Me) from a peer five seconds after opening the PR.
The Playbook: Reviews are a Safety Net, Not a Hurdle
Protect `main`: The `main` (or `master`) branch should be protected. Disable direct pushes and force pushes completely.
Always Open a Pull Request: No code should enter `main` without a PR, even if it's your own small fix.
Give and Get Thoughtful Reviews: A good review checks for logic errors, tests edge cases, and improves readability. Don't just check for style. A good PR description helps reviewers understand the context.
“Show your draft to a friend before handing it to the teacher.”
📚6. Documentation Debt
The Mistake
A repo with a two-year-old `README.md` that still says "TODO: Add setup instructions," making it impossible for a new team member to get started.
The Playbook: Document as You Code
Keep `README.md` Evergreen: Your README is the front door to your project. It must have a clear purpose, setup instructions, and examples. Update it in the same PR that changes the setup process.
Add `CONTRIBUTING.md`: This file tells new contributors how to set up their environment, run tests, and what your coding standards are.
Use Issue and PR Templates: Create templates (`.github/` directory) to guide people to provide the right information when they open an issue or PR.
“Every science experiment must have a lab report.”
🤖7. Over-automation Without Understanding
The Mistake
Copying a complex 20-step GitHub Actions workflow from another project without understanding what each step does. When it fails, debugging is impossible.
The Playbook: Automate Incrementally
Start with One Action: Your first action should be running your tests on every push. Get that working and stable.
Add Linting and Builds Next: Once testing is solid, add a linter to check code style, and then a build step if your project requires it.
Scale Slowly: Only add more complex automation (like deployments, code analysis) as the project's needs grow and the team understands the existing CI/CD pipeline.
“Add one robot helper at a time — don’t flood the classroom with machines.”
💥8. Losing or Corrupting History
The Mistake
Using git push --force on a shared branch, or performing a complex interactive rebase (`git rebase -i`) that accidentally deletes a teammate's commits.
The Playbook: Treat History as Sacred
NEVER Force Push to `main`: This is the cardinal sin of Git. Branch protection rules should make this impossible anyway.
Prefer Merge to Rebase on Shared Branches: Rebasing rewrites history. It's great for cleaning up your *local*, un-pushed commits, but dangerous on branches others are using. A standard merge is safer for collaboration.
Use `git reflog`: If you think you've lost a commit, `git reflog` is your time machine. It shows a log of every action you've taken, allowing you to recover "lost" work.
“Never tear pages out of your diary; even mistakes tell the story.”
🔒9. Security Blind Spots
The Mistake
Committing an API key, password, or other secret directly into the code. Even if you remove it later, it's still in the Git history forever.
The Playbook: Assume Everything is Public
Master `.gitignore`: Your first commit in any project should be a `.gitignore` file. Add patterns for secret files (`.env`, `credentials.json`), dependency folders (`node_modules/`), and OS files (`.DS_Store`).
Use GitHub's Secret Scanning: Enable this in your repository settings. It will automatically scan your code for patterns that look like secrets and alert you.
Use Environment Variables: Never hardcode secrets. Load them from environment variables or a secure vault service.
“Never write your locker combination on the notebook cover.”
♻️10. Reinventing the Wheel
The Mistake
Writing a custom shell script to send a Slack notification when a GitHub Action could do it in three lines of YAML.
The Playbook: Leverage the Ecosystem
Search the Actions Marketplace First: Before you write a script for CI/CD, search the GitHub Actions Marketplace. There's likely a well-maintained, community-vetted action for what you need.
Reuse Proven Workflows: Many Google projects have starter workflows. Look for existing `.github/workflows` files in similar projects and adapt them.
Customize Only When Necessary: Use existing actions as building blocks. Only write your own from scratch when your needs are truly unique.
“Borrow your friend’s ruler instead of carving one from wood.”
Test Your Git Instincts: 10 MCQs
1 of 10
Frequently Asked Questions
Alright, let's wrap up with a quick Q&A. These are real questions I've been asked by new developers during code reviews and mentoring sessions. There are no stupid questions when it comes to Git—we've all been confused by it at some point. I've grouped them by topic to make things easier to find.