Best practices and good habits
Look at Git’s status and history often
Use git status
and git log
(or other tools) to frequently check Git’s
state. The git status
command even gives useful hints for actions you could
take.
Read Git’s output and check if it succeeded
After doing a git
command, read the output. It’s possible the command failed.
Often when Git fails to do something, it will give you helpful hints to fix
your command.
When to commit
Commit when you’ve “done one good (small) thing”. This might be fixing a formatting issue, correcting a typo, refactoring a function, or adding a comment. Try to make your commits small and self-contained changes that can be easily described in a short commit message.
What to write in a commit message
Commit messages should be written in “imperative voice”, as though you are commanding someone to take an action. Commits messages should not end in punctuation. Commit messages should be less than 80 characters. Details can be added after a blank line.
Correct:
Add type signature
Create type annotations
Incorrect:
Add type signature.
(ends in period)Adding a type signature
(incorrect voice)Added a type signature
(incorrect voice)Made a type signature that says the arguments are both strings and the return value is an integer
(too long, incorrect voice)
When to create a branch
You might create a new branch for various reasons, e.g.:
Working independently on the same repository as a colleague: Branches enable you to work without conflicting with each other.
Trying multiple approaches to solving a problem: Branches enable you to quickly switch between approaches without them conflicting.
Isolating changes in progress from known-good state: If you only merge branches into the
main
branch once they are fully working, you can trust thatmain
will always work.
When to merge a branch
A branch should only exist as long as is needed to complete one “big thing”, like implementing a feature or fixing a bug. Merge it and move on once you’re sure you’re done with that thing. Some things are big and require long-lasting branches. You may want to break the large feature into smaller features, each of which are implemented in branches created from the large feature branch.
What to name a branch
Branches should be named after the goal of the branch. For example, if you’re
trying to fix the issue CMZ-123 in your JIRA which describes an issue with an
API document, your branch might be called CMZ-123-fix-api-documentation
. Or
if your team is planning to overhaul the documentation, you may have a large
branch titled documentation-overhaul
.