Minimal git for openstates developers

Git is a version control system developed by Linus Torvalds for use in the development of the Linux kernel and associated code. Some people describe git as "the tool Linus created to make other people feel stupid." If you are used to cvs or svn or even mercurial, git may be very confusing.

If you are not going to try to write code to be included in the openstates project, using git is easy. You can clone the repository and then, as updates occur, use 'git pull' to get changes that others have made. But if you are not going to contribute, why are you here, really? :-)

If you are going to write code that you want to be included in openstates, you will need to fork the repository. Then you can update your own fork on github and others will be able to see it and pull from it. Unfortunately, this adds a little bit of complication to getting updates that others have made. You can go to the github site, create an account for yourself and then go see the page https://github.com/sunlightlabs/openstates and hit the "Fork" button (near the top, on the far right from the "sublightlabs / openstates" title on the page). After just a few seconds, your fork will be created.

On your local system, you then clone your fork. It can be confusing, so try to keep this in mind. As you make changes, you can check them in at any time. Git encourages you to check in often and it is ok to do this. Checking in changes only the state of the local clone of your fork of the original repository. You can even combine your checkins. Say that you have committed to your clone 10 times, but you want to coalesce those into one commit that you are going to push to your fork. Maybe you want to do this so that your development process does not look quite so chaotic. You can do this. Do a search on 'git combine commits' and you will see the rebase command can do exactly this.

A lot of the documentation on git seems to assume you are a committer to a project. If you were a committer to openstates, your do this once:

 git clone https://github.com/sunlightlabs/openstates.git

And then you do this in the course of your work:

 cd openstates
 git pull (and deal with any conflicts that may arise)
 ... do stuff...
 git add <new file or two> (otherwise git will ignore new files)
 git commit -a
 git diff --color
 git pull (and, again, deal with any conflicts that may arise)
 git push
 ... return to "do stuff" ...

If you are not a committer, your process is a little more complicated. This is unfortunate, because if you are starting out with both git and openstates, you have even more to learn. You will do this only once:

 (got to github.com and fork the openstates repository into your account)
 git clone https://github.com/<your name>/openstates.git
 git remote add upstream https://github.com/sunlightlabs/openstates.git

You can use another word for "upstream" if you like. And then you do this in the course of your work:

 cd openstates
 git fetch upstream
 git merge upstream/master
 git pull (and deal with any conflicts that may arise)
  ... do stuff...
 git add <new file or two> (otherwise git will ignore new files)
 git commit -a
 git diff --color
 git fetch upstream
 git merge upstream/master
 git pull (and, again, deal with any conflicts that may arise)
 git push
 ... return to "do stuff" ...

This "git push" is only pushing code to your fork. So, when you want your stuff to be included in the main project, send a note to the list with your repository URL or issue a pull-request from your fork to the main repository and, if people like what you have done, your stuff will be pulled into the main repository.