My Opinionated Git Conventions
My (very) opinionated Git conventions. If you follow these, you will be much less likely to create messed up git histories, and your git setup will make much more sense.
Git Version
Make sure your Git is up to date. On macOS, install Git via Homebrew (don't stick with the default version shipped with macOS):
- Install Homebrew if you haven't: https://brew.sh
- Install Git via Homebrew:
brew install git
The latest version as of this writing is 2.51.0. You can find the latest version tag at the following locations:
Merging
- Do not EVER merge a branch into feature branches. This is the hardest common mistake to recover from.
- Do not merge
main,master,dev(or whatever you call your default branch) into feature branches. - Do not merge other features branches into your feature branch.
- Instead, when you need to update a feature branch, use
git rebase. - Not following this convention will not affect the default branch if the follow the next convention, so it's not a strict convention. However, when your branch's git history gets messed up and you ask me to help, it will be your fault that it takes a long time to fix :)
- Do not merge
- Merges are only acceptable for merging feature branch pull requests.
- Only use squash merging when merging feature branch pull requests: this produces the most clean git history.
Pull Requests
- Pull Requests (PRs) should be small and, as much as is reasonable, follow the Single Responsibility Principle (a single purpose per PR).
- A good target to reach for is one commit per PR, but, as mentioned above, be reasonable. One commit per PR is not required.
- Handle lots of small PRs that depend on each other by chaining them together.
- An example merge chain could be: default branch < feature A < Fix B < Feature C
- Use
git-virto merge and push changes from within a PR chain.git-vir push: to update a branch anywhere in the chain and automatically update all dependent branches.git-vir merge --squash: to merge the base of the chain and automatically rebase each branch in the chain.
- Always merge the PR pointing to the default branch (
main,master,dev), or the base of the chain, first. - If you choose not to use
git-vir, you'll have to manually rebase every branch in your chain.
Branch Management
- Call your default branch
dev(notmainormaster).devhas much more intrinsic meaning to it. - Do not use
git pull.- If your goal in using
git pullis to make your local branch match the remote copy of your branch, usegit reset --hard origin/<branch-name>. - If your goal is to merge your branch's local and remote changes together, use
git rebase(and you'll probably want to use the--ontoflag).
- If your goal in using
- Do not open PRs that point to release branches (like
prodorstaging). Do not merge into release branches.- Instead of merging into feature branches, directly push to them.
- For example, when releasing
stagingtoprodusing branches, run the following:git fetch origin staging
git push origin origin/staging:prod - When a hot fix is push to a release branch (
prodorstaging), always immediately open a fresh PR, with that hotfix, based ondev. This ensure that your next release does not delete the hot fix.
GUIs
- Do not use GitHub's "resolve conflicts". Fix them locally via the Git CLI.
- Do not use Git GUIs to run any Git commit or push operations.
- Run all commands in a terminal so you know exactly what commands are being run and so you have full control over them.
- Learn to use the raw commands, they will give you so much more power and understanding than relying on a GUI.
- If you wish, only a Git GUI (I recommend the simple one included with VS Code) for seeing what current changes you have as well as staging, reverting, or unstaging them.
Global Git Configs
Use these configs to save yourself a lot of time.
- Set the default upstream branch:
git config --global push.default current- This prevents you from ever needing to manually set your local branch's upstream branch name.
- Fix branch order sort:
git config --global branch.sort -committerdate- This sorts your
git branchoutput by latest branch.
- This sorts your
- Prevent auto branch tracking:
git config --global branch.autoSetupMerge false- This prevents new local branches from automatically tracking their base branch.