git.txt

There are many ways to collaborate using git or in our case github,
this document covers a few common ones. We assume you know a little
bit of git, and we'll skip the magic how to set up a git repository.

We first need to set some nomenclature:
 - users                  (u1, u2, ...)
 - repositories or repo   (r1, r2, ...)
 - files                  (f1, f2, ...)
 - branches               (b1, b2, ...) 

1) directly clone a repo and push back into it.
   This is officially dangerous, it also needs special permission
   from the owner but is the most simple sequence of commands,
   and not too different for those used to CVS and SVN.

	git clone https://github.com/u1/r1
	cd r1
	$EDITOR f1
	git add f1
        git commit f1
        git push

   This is the typical work if you work on your own repo and you just
   want to use it like a backup device.

   You can also use it on your own department machine and/or laptop,
   using ssh keys and bypass github.com alltogether.

2) A variation on this theme is using a branch, so they could be more safely
   merged into the master. So, instead of editing 'f1' in the master, we
   create a branch and make changes on that branch instead
   (you will often hear developers say "leave the master clean")

	git checkout -b b1         # create new branch, and switch to it
	$EDITOR f1
	git commit f1
	git push -u origin b1      # skip this if you want to keep it local

   When it comes time to merge, the following sequence can be followed

   	git checkout master        # switch to master
	git pull                   # make sure it's clean
	git merge b1               # merge in the b1 changes, watch for conflicts
	git push                   # push this back to github


3) fork the master in your own GITHUB workspace, clone from that to your laptop,
   work on a branch, and go a pull request on GITHUB from that branch, viz.
   (below your name on GITHUB is "gh_name")

   	1) go on GITHUB and fork the repo to your space
	   (see the fork button top right)
	   
	   https://astroumd/demo


	2) now on your laptop get your own version (as "teuben") where you edit
	   on the branch

	   git clone https://github.com/teuben/demo demo_teuben
	   cd demo_teuben
	   git branch b1
	   git checkout b1 
	   git branch               # shows you all branch names
	   git branch -r            # shows all branches on (my) remote
	   $EDITOR f1
	   git status
	   git commit f1
	   git push -u origin b1    # push it back to your GITHUB


	3) now go back to your GITHUB.COM space, and pick your "b1" branch,
	   and issue a PULL REQUEST
	   Wait for an email when this was merged by the coordinater
	   When this is done, your b1 branch was merged into the master
	   
	   On GITHUB you can do that pull request merge graphically, but they also
	   show you the command line sequence: (untested)
	   	# put teuben's branch into your repo
	   	git checkout -b teuben-b1 master
		git pull https://github.com/teuben/demo.git b1
		# merge those changes and push back onto github
		git checkout b1
		git merge --no-ff teuben-b1
		git push origin b1

        4) Fetch the new master now from the original provider, which we'll label as "upstream"

	   git remote                                                   # see which ones you have
	   git remote add upstream https://github.com/astroumd/demo     # add this if you don't have it

	   git checkout master                                          # make sure you're on your master
	   git fetch upstream                                           # fetch it
	   git merge upstream/master                                    # merge in 
	   git status                                                   # there should be no new things
	   git push                                                     # push it to your origin


         5) If you really don't care about that branch "b1" anymore, it can be deleted.

           git checkout master
	   git branch -D b1
	   git push origin --delete b1

The 'astropy' project has a nice writeup about their workflow:

http://docs.astropy.org/en/stable/development/workflow/development_workflow.html



*) lets say you have edited a file in the master, and realize it should have been done on a branch.
   Here's one way, with file 'f1' and branch name 'b1':

   mkdir tmp
   mv f1 tmp
   git checkout -- f1
   git checkout -b b1
   mv tmp/f1 .
   rmdir tmp