Mini GitHub Tutorial

How to Use Github for Processors

1. Read a GitHub tutorial. There are many good ones on the web. The trickiest thing with Git is understanding branches. This tutorial might be helpful: http://git-scm.com/book/en/Git-Branching-Branching-Workflows. This is a more detailed tutorial, if you really want to understand how things work (although the instructions below might be sufficient for most things): http://ftp.newartisans.com/pub/git.from.bottom.up.pdf.

2. To get a copy of processors and start working with git, please follow these steps:

git clone https://github.com/clulab/processors.git

Similar instructions exist for all other projects hosted in GitHub.

3. By default you will be in the master branch. To see what local branches you have, and which one you are in, type (the branch marked with "*" is the branch you are in):

git branch

4. Please work from your own branch for every major change (see next section for best practices). To create a new local branch, type:

git checkout -b my-new-branch

5. After you make some changes, you can the status of files with git status. To add a new file and then commit it, use the instructions below. Note that, if you your comments are very verbose (and they should be!), it is best to use git commit: this will open a separate editor where you can type your commit message.

git add my-new-file
git commit -m "Description of my first commit"

You might find these tips on good commit messages helpful.

6. You have to publish the changes in your branch to a remote branch, so that other people can see your contributions. You do this by:

git push origin my-new-branch

7. When your changes are ready to be merged into the master branch, check with your advisor about which protocol to use. For some projects that are more sensitive (e.g., processors or reach) merges into the master branch are handled using pull requests. Follow step 8 if you are in this situation. For other projects, merging into master may be directly allowed. In this situation, skip step 8 and follow step 9.

8. If your supervisor indicated that your contributions must be merged into the master branch using a pull request, please follow the instructions in this page to initiate one: https://help.github.com/articles/using-pull-requests/

9. If your supervisor allows direct merging into the master branch, do:

   git co master (which switches to your local master branch)

   git pull origin master (which updates the local master with changes published in the remote master)

   git merge my-new-branch (merge your local branch into local master. Resolve any conflicts reported by git here, if necessary.)

   git commit -a (commit the merged master locally. Summarize the changes made in your branch in the commit comments. Note: this step is not necessary if the merge above completed successfully without any manual editing.)

   git push origin master (push the updated local master to remote master)

General Best-practice Rules for Github

• It is important to keep the remote master (origin master) clean. That means, do not merge your branch back into master if it's not in a stable state. Unit tests must always pass in the master branch!

• It is important to create a separate branch for every major change (i.e., research idea) you make. Merge branches back into master as soon possible, but only when: (a) the idea was proven to work, and (b) see previous rule.

• Do not create too many levels of branching, that is, branches spin-off from another branch. Keep your branch structure as flat as possible, ideally a one-level tree where every branch is a child of "master".

• Use your remote branch (step 6 in the previous section) as a place to backup your changes before merging back into master.

Useful Tips

• To save some typing, edit your ~/.gitconfig files and add aliases, e.g.:

[user]
  email = [email protected]
  name  = Your Name
[alias]
  st = status
  ci = commit
  br = branch
  co = checkout
  ls = ls-files
  discard = checkout -- .
[push]
  default = tracking

• It is very useful to display your current working branch in your Bash prompt (for *nix and Mac folk). You can add the following block to your ~/.bashrc file:

# first, copy [`git-completion.bash`](https://github.com/git/git/blob/master/contrib/completion/git-completion.bash) to `~/.git-completion.bash`
source ~/.git-completion.bash

To ensure the completions are available each time you log in, add the following to your ~/.bashrc:

# bash-completion
if [ -f ~/.git-completion.bash ]; then
  sh ~/.git-completion.bash
fi

Similar completions are available for [other shells (ex. zsh) as well]((https://github.com/git/git/blob/master/contrib/completion/).

• If you messed up your current branch, did not commit the changes, and just want to revert to the last checkin, use:

  git checkout -- . or (if you added the alias above)

  git discard