Personal guide for using git with GitHub
Git style guide. This is personally how I use git, which is similar to the Express and the iojs teams' style.
Merge branch 'master' into branch 'master'
If you ever see a commit that merges a branch into itself,
just run git rebase
and it will clean itself up.
Merge branch 'master' into branch ...
If you're merging a parent branch into a branch and see this commit, you merged wrong.
Type git rebase master
(or whatever the master branch is) to get rid of this commit.
If possible, don't click the big green "Merge Pull Request" button.
Doing so creates a Merge branch...
commit, which is noisy.
However, if you do this, you should always reference issues that this commit solves in the commit title or description.
There are a couple of ways to add this:
git rebase
- only when you replay the commits, which is not always the case if the merged branch is already fast-forwarded.git commit --amend
So that they adhere to your styles:
git merge --squash
When merging your own branch, you could use git merge --squash
to squash all your commits.
I only say "merging your own branch" because doing so replaces the original author with you.
Thus, you are unable to properly assign blame.
My personaly way of merging branches is the following:
Checkout the branch, rebase, and force push:
git checkout master
git pull
git checkout feature
# Maybe squash and amend
git rebase master
git push -f
If rebase does nothing, just do a git commit --amend
.
The main reason is that you'd want the commits you merge to match the commits in the branch exactly. This will tell GitHub to automatically close the pull request when you merge it like so:
git checkout master
git merge feature
git push
git rebase master
all day every dayDon't diverge from your main branch as your problems will only exponentiate.
git rebase master
git push -f
Squash your commits frequently, but you should always squash it before merging. You do not want or need your working commits (ex. a commit adding logs, another removing them) in master as it's noisy and effectively negates itself. Squash them out!
Another good reason to squash often is to make rebasing easy. If you have a lot of commits, each commit is a potential merge conflict. When you only have a single commit, you only need to do merge conflict resolution once!
git push -f
to only branches you ownMake sure you only push to the current branch! There's a git config option for this, I don't remember what it was. You do not want to overwrite shared branches unless everyone else knows!
For example, readme: adding docs on stuff
.
For example, closes #56 closes #57
.
When the commit gets merged,
GitHub will know to automatically close these issues.
If you're working in a repository that is a fork or is expected to be a fork,
expand the issue like closes jonathanong/git-style-guide#56
.
For example:
deps: :arrow_up: koa@~0.16.0
Set a standard for your team. Currently, I only do arrows for dependency changes. It makes git way more fun!
Make sure the maintainer knows what's going on.
/cc
them or assign them.Especially in teams where you want to know what others are working on. It also helps to have others look at your progress so they make sure you're not making any obvious mistakes and that you're on the right track.
Let the maintainer do the versioning. The primary reason is that this commit could be included with other commits, which may warrant a different version. Thus, adding a commit that has a version in it makes everything more confusing.
Always rebase your pull request so that it can be cleanly merged.
Squash your commits appropriately - there should be as few as possible. There should not be any working commits, ex. commits where you add a log followed by another commit where they're removed. There should not be any "merge" commits
If the pull request needs some minor touch ups, don't always bother asking the collaborator to fix every tiny detail. Sometimes it's just easier to make those changes yourself, then squash the commits so that they still have the credit.
For example, don't be so finicky with style changes (you should lint in your CI testing service anyways) or phrasing. Just make those changes yourself.
If a pull request includes commits you are not interested in,
ex. version bump commits, then simply cherry-pick
the commits
you're interested in. The collaborator will still get credit
and you don't have to bother asking the collaborator to "remove those commits".