Git Best Practices

A few ideas to make your use of git more effective and enjoyable.

1. Learn to use git from the command line

A good place to start is the GitHub help:

https://help.github.com

There's a section at the bottom called Bootcamp that takes you through setting up Git, creating a new repo (option 1), forking an existing repo (option 2), and the social networking features of GitHub.

There's a good introductory screencast video about using git from the command line here:

http://vimeo.com/33631836

Then, it's time to go deeper and develop a detailed understanding about the rationale for using a distributed version control system (which is what git is) and how a DVCS can make life easier for a software developer. Chapters 2 and 3 of the following ebook cover these subjects in detail. Understanding this material is really a prerequisite to using git effectively, either alone or (especially) on a team:

http://git-scm.com/book

Now that you have a better understanding of what git is and how it can help you, learn how git's (killer) branching feature can be applied in a typical team environment throughout the life of a software product:

http://nvie.com/posts/a-successful-git-branching-model/

2. Commit Often

Any commit that is larger than a few lines of code probably should have been broken up into multiple commits.

Some examples of code changes that need their own commit:

• Adding a file or a set of files for a single purpose
• Removing a file or a set of files for a single purpose
• Changing the functionality of a method
• Changing the parameters of a method (e.g., adding a boolean to the parameters). This commit should include the propagated changes in the rest of the code
• Adding a new method (this commit will usually include the statements where the new method is used)
• Removing a method (the commit message details should specify why this method was removed)

It's a good idea to keep a command prompt open so that you can quickly issue a commit after completing any kind of incremental improvement to the code.

3. Make commit messages descriptive

If you're making the commits small enough, there's no reason the commit message can't be concise but complete. The message should describe what has changed in that commit. Then, when looking at the history of commits in a branch, you will see a trail of breadcrumbs explaining exactly what has been done to the code in what order. This makes the code very easy to review or fix later. It also helps when transplanting some useful bit of functionality to a different project.

4. Always pull from the main repo before pushing to your fork

In most collaborative work using github, the main repo is managed by an admin, but all of the team members have their own fork of that repo on github. People work on different parts of the project on their local machines and then contribute their work to the main repo. However, getting that new code into the main repo is a multistep process:

1. Pull from the main repo to make sure your local version is up-to-date and free of merge conflicts. You can do this anytime, but the one time you must do it is just before step 2. Merge conflicts are inevitable and they're much easier to deal with on your local machine.
2. Push to your fork on github. Since you have already merged in any recent changes in the main repo, you can push to your fork secure in the knowledge that there won't be any conflicting lines of code.
3. Issue a pull request from your fork to the main repo.

5. Make a new branch before working on a new feature or issue

Branching provides protective insulation for your main branch when working on something new. It also makes work on a particular issue easier to find when looking backward in time. Of course, if your work in the branch successfully addresses the issue, you'll want to contribute that code to the main repo. One way to do this would be to first merge the issue branch into your local develop branch and then follow the above steps for contributing code to the main repo. However, a better way to do it is to push the issue branch to your remote fork, then issue a pull request from that branch to the main repo's develop branch. That extra step ensures that the issue branch survives intact and lives on in your fork in github. So, assuming your newly finished local branch is called issuex, the complete merge maneuver would look like this:

1. Pull from the develop branch of the main repo into the local issuex branch and resolve any merge conflicts.
2. Push to the issuex branch of your fork in github (i.e., git push upstream issuex <-- will create the issuex branch in github if it doesn't already exist).
3. Issue a pull request to the develop branch of the main repo from the issuex branch of your fork.
4. After the pull request is processed, pull from the develop branch of the main repo to your local develop branch.
5. Push your local develop branch to the develop branch in your fork.