When it comes to talking about git best practices, a lot of people seem to point toward the git-flow branching model. Personally, there are things I like about it (hotfix branches) and things I can't get past (a preference for merge commits..ewww). I think with some tweaks, it could be a reasonable model for medium to large development teams. But I tend to work with small teams and I don't have actual experience with git-flow, so I'm going to stop talking about that.
Here's what I do have experience with: How I Use Git
Contents:
master
branch is like subversion's trunk
. Successful projects tend to keep these in a state where releases can be made with minimal effort. Therefore, only code that has been fully tested is allowed in.MYPROJ-42
, name the branch myproj-42
.git branch -d branchname
. To remove a remote branch, git push origin :branchname
.v1.0.0
". I like this convention (including the trailing zero) because the Major.Feature.Bugfix convention is compatible with semantic versioning and is commonly seen with Maven artifacts.Merge commits are ugly. Nobody likes them and they smell funny. Here are some tips for avoiding them:
git pull
to get remote changes, if you have any local commits that haven't been pushed yet (wait, you're not working directly on master, are you?), specify --rebase
(you can also make this the default option as explained in this article). This will modify the sequence of commits to your local repository so that your locally-committed changes appear after those you just pulled. Now when you push your changes, your fellow committers will just see an incremental set of changes with yours at the end, and it will make sense to them.git merge yourbranch
, by default, git will attempt to do a fast-forward commit if possible. It's not possible if there are any changes in master that aren't already in your branch. In this case, before attempting to merge your changes into master, switch to your branch and type git rebase master
. This will put all the new commits from master in your branch, behind your changes. Now it should be possible to fast-forward merge your branch into master by switching to master and typing git merge yourbranch
git pull --rebase
or a git rebase master
will fail due to a conflict. In that case, see this excellent article, which covers resolving rebase conflicts.Before pushing the changes from an issue branch to the origin master branch, it's useful to be able to do a little surgery on them so they make more sense to others. Squashing commits allows you to turn a high number of commits into a low number, with the same resulting code. The sequence of commits get "squashed" into a smaller number of commits. Re-wording lets you completely change the commit message for any number of commits.
You can use an interactive rebase to do one or both of these. Let's say you're on a branch and you want to squash the last 3 commits into one and reword the commit message. First, run:
git rebase -i HEAD~3 |
The editor will come up and basically guide you through the rest of the process. In this case, you'll want to change the first line to begin with "r" (reword) and the following two lines to begin with "s" (squash into previous commit).
If there's a tracked issue associated with your commit (ideal):
MYPROJ-42: Feature/bug description under 50 chars if possible Longer description, if needed. Don't exceed 72 lines here. A blank line between sections is ok if multiple sections of text are needed. https://example.org/path/to/tracker/MYPROJ-42 |
Otherwise (it's a small change/typo fix, etc.):
Fix testing errors introduced by last commit |
Notice the following conventions:
After using git for a little over a year, here are a few (Unix-based) tools I've settled on.