Git records the history of your code so that several people can work on it at once and undo mistakes. A clear workflow keeps that history useful. This guide describes a simple approach that works well for small teams.
The core idea #
The main branch always holds code that works. Every change starts on its own short-lived branch, gets reviewed, and is merged back. Nobody commits directly to main.
Step by step #
- Update main. Pull the latest changes before you start.
- Create a branch with a descriptive name, such as fix-login-error or add-invoice-export.
- Make small commits. Each commit should do one thing and leave the project in a working state.
- Push the branch to the shared repository.
- Open a pull request that explains what changed and why.
- Review and test. A teammate reads the change and automated checks run.
- Merge once approved, then delete the branch.
Writing good commit messages #
- Start with a short summary of 50 characters or fewer, in the imperative mood: “Fix login redirect”, not “Fixed” or “Fixes”.
- Add a blank line and a longer explanation if the reason is not obvious.
- Mention the issue number if you track work in an issue tool.
Keeping pull requests reviewable #
Small pull requests get better reviews and merge faster. As a guide, aim for changes a person can read in about fifteen minutes. If a feature is bigger, split it into steps that can each be merged safely.
Merge, squash or rebase? #
- Merge commit: keeps every commit and shows where branches joined.
- Squash merge: combines the branch into one tidy commit on main.
- Rebase: replays your commits on top of the latest main for a straight history. Do not rebase branches that others have already pulled.
Pick one rule for the team and stick to it.
Handling conflicts #
A conflict means two changes touched the same lines. Git marks both versions in the file. Decide what the final code should be, remove the markers, run the tests and commit. Updating your branch from main often keeps conflicts small.
Habits that save time #
- Use .gitignore so secrets, build output and dependencies are never committed.
- Never commit passwords or API keys. If you do, treat them as leaked and replace them.
- Protect the main branch so that reviews and checks are required.
