Below is our current practice for using Git (the technology) & Github (the repository) when collaborating on projects. This process assumes that you already have Git installed & configured, and there is an existing project repository on Github with a "development" branch already setup.
If you do not have Git installed, follow these instructions.
This process also assumes that you are using the command line, however most of these tasks can be performed with a desktop client like Github for Mac or Tower.
1.) Open terminal and locate the project directory you wish to use.
$ cd ProjectName/Code/webapp
2.) For new projects (or existing projects not using Git), initialize a Git repository in your current, working directory. For existing projects already using Git, skip to step 4b.
$ git init
3.) Add the remote SSH address of the project on Github to your local repository. The address can be found on the right-side of the project page, just below the settings menu item.
$ git remote add origin git@github.com:username/project-name.git
4a.) If this is your first time checking out the project, you'll need to fetch the remote branches available and checkout a copy of the development branch.
$ git fetch origin
$ git checkout development
4b.) If you already have a copy of the development branch locally, you can simply pull from the remote development branch to get all of the latest changes.
$ git pull origin development
5.) Create a branch off of development, naming the new branch based on the changes you plan on making. Then checkout that new branch to make it your current working branch.
$ git branch home-page-bug-fix
$ git checkout home-page-bug-fix
6.) #DoWorkSon
7.) Add the files that you have changed and you wish to commit (save) to the 'stage'. Commit your changes and write a meaningful message that explains your commit.
$ git add index.html
$ git add styles/style.css
$ git commit -m 'Fixed logo styling on Home page'
Ideally, you want to make small, meaningful commits throughout your workday based on the different changes you make. For example, if you are developing a new page for a website, you can make a commit for each feature or component you add to the page.
8.) Once you are done, push your changes to a remote branch with the same/similar name.
$ git push -u origin home-page-bug-fix
This can be done at the end of the day, or once you are finished with all of the changes you plan on making for a specific task. Following the previous example, you can can push your changes to remote once you've completed the new page for your website or at the end of the day, whichever comes first.
9.) Go to the remote repository on http://github.com, and make a pull request from your branch in to the development branch. If you've recently published the branch, Github will provide a notification on the main page of the repo to make a pull request. Otherwise, you can click the 'Pull Request' menu item in the right-side navigation.
10.) If making a pull request in to a collaborative branch, ie. development, make sure to prepend the title with '[Code Review]' so your team knows that your code needs reviewing before merging. Below, write something meaningful about what's in your pull request.
11.) Make sure to inform the other team members of the project about your pull request by including them in your message. When your done, click 'Send Pull Request'. This will notify your team members by email that there is a pull request waiting for review.
12.) After your team has reviewed the code and okay'd the changes, you can merge the changes in to the development branch by clicking 'Merge Pull Request'.
13.) Make sure to include the name of the team member who okay'd the request in the comment section of the 'Confirm Merge' textbox. Then click 'Confirm Merge'.
14.) Once the merge has completed, delete the remote branch that was merged in to development by clicking 'Delete Branch'. We no longer need it since all of the commits (changes) are now in the development branch.
You're done! If you want to start making new changes or work on new features for the same project, you can start over at step 4b. Ideally, you want to make a branch for each feature/component that you are working on, so there is more accurate account of the history for a given project.
There are a few extra commands that can help you out during development while using Git.
- git status: This is probably the handiest git command.
git statuslets you know what branch you're currently on, what changes have been made but are unstaged, what changes have been staged and are ready to be committed, and any untracked (new) files there are in the project. For example:
$ git status
# On branch style-changes
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: index.html
#
# Changes not staged for commit:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: styles/style.css
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# README.md
- git branch: This command displays a list of your local branches. If you want to see the remote branches, you can use the
-rflag, i.e.git branch -r. You can also view all of the remote branches on Github by clicking the drop-down menu on the main page.
If you are unfamiliar with the Git Workflow, this can be a lot to take on. Eventually, this will become second nature as you follow this process on a daily basis. You can also take comfort in the fact that if you make any mistakes, they can be tracked down and reverted fairly easily because we're using a tool like Git.
If you would like to learn more about Git, below are some excellent resources available online:
- Git Immersion: A guided introduction & tutorial through the fundamentals of Git
- Try Git: An interactive CodeSchool course on the basics of using Git via command line. Very fun!
- Pro Git: The entire Pro Git book, available for online for free. Great Resource
- Git Ref: a reference site for Git; essentially a glossary for all Git related commands
- Github Guides: A collection of video tutorials on using Github by Github.