News Archive
PhpRiot Newsletter
Your Email Address:

More information

On feature-branches and pull-requests

Note: This article was originally published at Planet PHP on 18 April 8120.
Planet PHP

Everyone and their mother uses Git + GitHub combo these days. A lot of open-source projects accept patches using github's pull requests, becausea well, because it is the easiest way to review and accept patches.

But, novice Git users don't know how to do this optimally, and aonaivea approach leads to complexities. Git is a distributed version control system, which means that everyone can aocommita to their copies of repositories. Syncing these commits with upstream is a bit more difficult and leads to commit-conflicts sometimes. So, here's aforementioned aonaivea approach:

  1. Fork upstream github repository
  2. Clone forked repository to local machine
  3. Make changes
  4. Commit
  5. Push
  6. Send Pull Request

It will work, but, there's one non-obvious thing: pull request, probably, won't be merged immediately and there are high chances, that there will be some commits commits pushed to official repository before our commit is merged. As the result, we have a conflict between upstream repository and our forked repository. So, at this point, if we plan to use our forked repository again, we have to aomergea upstream changes. It's not end of the world, and git, if we're lucky enough, will do this merge automatically as part of aogit pull upstreamao, but it won't be aofast-forwarda merge and github's aoNetworka diagram (or branches diagram in your favourite git GUI) won't be nice and clean anymore.

There's better approach, and it's name is aoFeature Branchesao. It's quite simple. Once you have cloned forked repository (i.e. after steps 1-2), use aogit checkout -b new_branch_namea command (it's nice, if aonew_branch_namea summarises changes you're going to implement). This command creates new branch, starting from current aomastera and makes it active. Make changes and commit them: aomastera branch is left intact and all the things you changed sit nicely in this new branch. Now, push these changes with aogit push origin new_branch_namea command. This will send your new branch to github. Now, open this branch on github and send Pull Request from your aonew_branch_namea to upstream's aomastera, as usually.

Use aogit checkout mastera to return to the aomastera branch, and, whenever upstream merges your changes, and you pull those, they will appear here automatically, without a single aomergea effort from you. As a bonus, you get beautiful tree of branches without complex knots.