Nine months later, the owner of the repository finally noticed my pull request (I’m not confident I submitted it correctly), and was glad to add my code, but needed me to actually do it properly. I fumbled and spent hours trying to figure out how to change the format and name of the file I had created in my repository and standardize my contribution and ended up having to start over from scratch. Another six to nine months after that the repository was closed and moved to a new one and my contribution isn’t in the new one so I’m not really sure what happened.
Six months after that, I started taking DWA15 at Harvard Extension School and got a proper tutorial on how to use Git, and I finally realized I had done it all wrong.
In retrospect, the biggest stumbling block was that all of the documentation that I could find about using Git is written for programmers by programmers. They already understand version control, they already know how to use the command line, and when they read the jargony description of what Git, GitHub, and Github.com are they understand it and don’t make basic mistakes like I did.
So I thought I would create an explanation of Git and Github.com for the rest of us.
First of all, Git (and GitHub) is the software you install on your computer to sync your files to Github.com. Git is the command line version, GitHub is a GUI application. The web interface for Github.com is not for content creation. You can do some very basic stuff like edit your README file but ignore the option to create a file directly on Github.com. (Want to see what happens when you do this? Try downloading my Google Apps Scripts repository.)
Mostly the purpose of Github.com is to have an easy way to view past versions (that whole version control thing). Think of it as viewing the Revision History in Google Docs. You can’t edit the past versions, but you can restore from a previous point. You can also do this in the GitHub GUI. Github.com also provides an easy way to sync files between a computer and a server without needing to use Fetch/WinSCP/Cyberduck/etc.
And of course Git et al. is also useful for collaboration on a project. You can “fork” projects (save a copy to your own set of repositories), you can create “branches” that serve as development environments that can be merged with the “master” (production) later on, and you can submit “pull requests” to have your contributions added to the shared master version. The basic workflow is you create your own copy, edit that copy, and then ask that the changes you made be added to the original.
Now that you get the big picture, you want to dive in, right? Right? (I swear it’s easy once you understand the correct way to do it, rather than whatever it was that I did that first time.) Here are a few recommended tutorials, most of them courtesy of Susan Buck and DWA15:
- A command line primer and Learn Python the Hard Way’s command line tutorial
- Very clear instructions for beginners on version control and setting up Git and Github.com (Read notes 00-09, skip 03 if you aren’t using a local server as a test environment and just initialize git in a folder on your desktop)
- Instructions on using the GitHub GUI
- Instructions on working collaboratively on a project