We get questions about Git, using Adafruit code published on GitHub, and making pull requests. Version control is a big subject, and this guide is far from comprehensive - it's meant to be a starting place and a pointer to other, deeper resources. We'll update it as things come up.
With that out of the way, let's get started with some basics.
If you've ever worked on a long-term project on a computer, especially one that you have to share with other people, there's a pretty good chance you've found yourself looking at something like this:
This has been a problem forever: You've got a project made out of files - something like the source code for an Arduino sketch or a Raspberry Pi project in Python, for example - and as you work on it, you need to know things like:
- What the last stable, known-good version looked like.
- What version is deployed to hardware in the field.
- When, roughly, it was last changed.
Version control systems, also variously known as revision control, source control, and so on, have been around since not long after programmers first started to grapple with this problem. A lot of their core ideas can be found in classic Unix utilities like diff and patch, designed to examine the differences between individual files or apply changes to them from elsewhere. Nowadays, a respectable VCS can usually:
- Store a project's entire history in a single directory.
- Track exactly how individual files changed, and when.
- Track who they were changed by.
- Log human-readable descriptions of changes.
- Merge sets of changes from different people.
- Display the differences between any two points in a project's history.
- Store multiple concurrent branches of a project, with different changes on each.
Git is the most widely used VCS in the open source community, and GitHub, a web-based platform for hosting Git projects, has become the go-to place for collaborating on source code, supplanting sites like SourceForge and Google Code.
Even though it's not a perfect fit for hardware and design-oriented projects, companies like Adafruit and SparkFun who focus on open source hardware routinely use Git and GitHub to track product changes, publish code and design files, and manage input from the community.
Professionals have used tools like SCCS, RCS, and CVS for decades, along with various and sundry commercial offerings. For a lot of users, though, especially small shops and hobbyists, version control didn't really begin to seem easy or straightforward until Subversion, frequently abbreviated "svn", showed up on the scene. Subversion was free, relatively easy to configure, and much less painful to use than earlier systems. It retains one strongly limiting flaw, however: It requires a central server to store changes and share them with others. It operates sort of like a hub and spokes:
Even as svn gained traction with users and gave many their first taste of robust version control, a new wave of open source VCSes came on the scene with a very different approach: Instead of relying on the hub-and-spokes client-server model, these tools would store a project's complete history locally, in a single repository. For example, with Git, all you have to do to create a new project is this:
mkdir project cd project git init
And since every copy of the project is a first-class citizen, with all of the project's history, it's not even strictly necessary to have one central copy of the project (though it's usually convenient). Changes can be moved around from copy to copy, and a "server" can be as simple as having a copy on a computer everyone can access with SSH.
Git, originally written by Linus Torvalds for use in developing the Linux kernel, has more or less taken over the world since its introduction in 2005. That's not to say there aren't other interesting options - tools like Mercurial, Darcs, and Bazaar offer similar features and friendlier interfaces, and are still actively used and maintained - but Git had some advantages in speed and tooling, plus some prominent early users. Once GitHub really started to take off, Git began to seem like the obvious choice to a lot of developers.
As a working programmer, I currently have somewhere around a hundred source code repositories on my laptop. Most of these are tracked with Git:
Among these are applications I routinely use, websites I maintain, variations on the Linux kernel, projects for Adafruit guides, and even the text of books I've written. If it's made out of text files, it's probably useful to keep it in Git. (If it has big binaries in it, this becomes a trickier question - we'll get to that.)
At the time of this writing, Git and GitHub are so widely used that even if you plan to use another system for your own work, knowing the basics is almost certain to be helpful in working with other projects.
Text editor powered by tinymce.
