csc302h — engineering large software systems — winter 2014

prerequisites

this howto assumes that you have already made a clone of your group's git repository, somewhere that you can work with it. for more information on cloning your repo, refer to this howto guide.

using git to stage & commit local changes

assuming you are in the directory containg your freshly cloned matplotlib repo, lets ask git what the status of your local copy is:

as you can see, you are on the master branch (you only have one) and that there are no changes to commit. so, lets make a change to a file in our repo:

in the image above, you can see that i've added a call to the print function just after all the imports in the pyplot.py module. lets check our local repo status again:

ah ha! git noticed that we now have a local change, and that it has not yet been staged for commit.

one great thing about git is that it always tells you what to do next. if you look at the image above, you can see that git is telling you what to do to stage the changed file to commit to your local repo:

(use "git add ..." to update what will be committed)

or, if you accidently changed the file, or otherwise want to overwrite the change with what's in the local repo:

(use "git checkout -- ..." to discard changes in working directory)

and it even suggests a way to stage the change(s) for commit and commit them all at once, as the last line of output from the status command, assuming you are a pro!

lets assume we want the change, so we'll do as git suggests and stage it:

note that if we had multiple changed files we should have staged them all at once with the --all flag to the git add command. to see everything you can do with the add command, run:

> git help add

and to see all of git's commands, run:

> git help

ok, back on track now, after staging the chage (see highlighted command) we then ask git for status again. notice now that it showes the staged file (in green if you have colours configured), and it tells you how to unstage it if you like. instead of unstaging, lets assume we want the change, and commit it, to our local repo:

the quoted bit after the -m is a commit message describing the change i made. always add a commit message describing your changes! at this point, we have committed our change to our local repo. this is fine if we aren't working with anyone else. if you want to get changes made by your group members, and let them have your changes, we need to lear how to push and pull from eachother, or from another, shared repo. the easiest way to do this is to use the repo from which you created your clone, the origin repository.

using git to push & pull changes to & fro

it's always good practice to pull before you push. this will allow you to see if your local changes will conflict with anything in the repo you are pulling from (the origin in this case). also, it will give you the opportunity to test your changes along side those of your group members to see if there are any issues before giving it to them.

so, lets do it, lets pull from our origin repo:

notice that we were prompted for our username and password this time. this is because our group's (origin) git repo on cdf uses https password authentication. so, any time we interact with the origin repo (clone, push, pull) we'll get prompted.

ok, so we're up to date, great! if there were changes, git would attempt to auto-merge them for us. in the event that the auto-merge failed, we'd have to merge them by hand. that is something we'll cover elsewhere.

ok, now we are finally ready to share our changes, in our local repo, with the rest of the group bu pushing them to the origin repo:

and that's it! now your group members can get your change by running the pull command in the directoruy containing their own local repo.

final remarks

so this concludes our brief csc302h git tutorial. we didn't cover manually handling conflicts and merges, which is something you will need to master later. there are also a plethora of other things you can do with git, so please treat this as the bare minimum to get by in csc302h. i encourage you to seek out some of the many excellent git tutorials on the web and learn how to do things like:

• configure console colours
• create shortcuts for git commands like: status, commit, checkout, etc.
• use branches with git to implement a workflow
• tell git (via .gitconfig) to cache your login credentials to avoid entering them repeatedly
• fetch & merge the master branch of matplotlib from github
• many more...

hope that was helpful!