GitHub Best Practices - bblockwood/lab GitHub Wiki

See here for the digital version of Pro Git by Scott Chacon and Ben Straub, which contains everything you need to know to use Git like a pro.

See here to download the Sourcetree Git GUI for Windows and Mac.

In addition to using GitHub issues for managing tasks (as described on the Task Management page), we use GitHub for version control and project management in general.

Version Control

We use Git to save and share versions of our code (and other files) with others as projects progress. After cloning a repository onto your local system, there are three main actions involved in this process:

  • Creating a commit: This packages and makes a record of the changes you've made on your local system. Note that all of the changes that you've made locally do not have to go into your latest commit--you can choose which changes to add to the commit.
  • Pushing a commit: This pushes your changes from your local system onto the remote version of the codebase. You may encounter conflicts at this stage if something you're trying to push conflicts with something someone else has recently pushed (but that you hadn't pulled yet).
  • Pulling a commit: This brings others' changes from the remote version of the codebase onto your local system.

It's a good practice to commit your in-progress work at the end of each workday, so it's accessible to collaborators (which also helps in pre-empting conflicts) and so it's stored remotely where it's safe from potential loss. Adding descriptive messages to your commits and tagging issues in your commit messages may also help you (and others) down the line when reviewing past versions of your code.

Working from the Command Line

See here for "Chapter 2.5 Git Basics - Working with Remotes" from Pro Git for an introduction to managing remote repositories via the command line. Below, a few key commands are summarized, with a link to the full documentation of the command in parentheses:

  • git clone url (doc): Copies the contents of a remote repository at url onto your local system.
  • git fetch origin branchname (doc): Downloads branch branchname from the remote version of the repository onto your local system.
  • git pull (doc): Brings pushed changes from the remote version of the repository onto your current local branch.
  • git commit -m "message" (doc): Creates a commit with the message "message".
  • git push origin branchname (doc): Updates the remote version of the branch branchname of the repository with your latest commits.

Working with Branches

Branches are often helpful for testing changes to code while avoiding conflicts and preserving versions of the codebase. Below are three types of branches we commonly use:

  • master: This is the main branch, which includes the current state of the working project, with all completed work from recent issues.
  • release: This branch preserves the codebase that corresponds to the version of the project that is currently being circulated.
  • iss##-description: Branches of this form are created for working on in-progress issues (with corresponding numbers ##, and a one- or two-word description) to avoid conflicts. Once all tasks relating to the issue are complete, we first merge master into the branch for the issue (to bring it up to date with master) and then merge the branch into master. Finally, we delete the branch for the issue.