(work in progress – kids woke up before I was done but I wanted to share what I had, updates will come)
Few things are more awesome than being curious and being able to spend a few bucks on a small board to follow your curiosities. There is a lot of fun ahead, but there are also going to be frustrations. I’ve been a professional software programmer for almost 20 years and I am frequently still stumped. When you hit these times, don’t be discouraged, ask questions and experiment because the success is worth 100 frustrations. I promise you.
I’m writing this because I’m in a couple Raspberry Pi groups on Facebook, and I see questions about better ways to store scripts and save documents every couple of days. If you’ve asked that, your instincts are spot-on, and even if you’ve never written a line of code this instinct alone puts you above about 10% of the people I’ve ever interviewed for a job. It probably also means you’re experimenting with code a bit (experimenting with code is how you get past those frustrations), and you need a better way to keep track of your changes than naming your files “led.py.new.old.old.1.old”. Been there, done that. Let me explain the better way.
BTW – this blog post is meant to complement and explain already available documentation, not replace what exists. So I’ll explain the fundamentals of what you’re doing but link to official documentation.
What are GitHub and Bitbucket?
GitHub and Bitbucket are two commercial services which provide source code management (SCM). This means they’re meant to keep your code files safe and organized, and keep a history of your changes. You can use this history to make something work, commit that working file, then screw it all up on your device trying something new, then be able to retrieve a previous version. Because of the version history, you’ll sometimes hear these called “version control systems”, or just “VCS”.
Both GitHub (GH) and Bitbucket (BB) offer free plans with both public (for sharing) and private (because sometimes my code is embarrassingly bad when I’m tinkering) repositories. They both offer very similar features, either one is a good choice for you, but GitHub is a lot more popular in the open source world. I used Bitbucket for my personal work for a long time, but the popularity of other projects made GitHub my main system now.
Both GH and BB are based on an open source version control system called “git“, which was developed in 2005 by Linus Torvalds to use for developing Linux (see https://en.wikipedia.org/wiki/Git for the rest of the story). GH and BB provide the cloud-based server side of keeping your code safe, you’ll still need something on your computer. The basic git uses the BASH command-line shell on every OS (Linux, Mac, Windows, Raspbian, etc.), but there are also plenty of GUI clients available. Because Rapsbian is derived from the same Linux kernel as Ubuntu, almost anyone which runs on Ubuntu will run on Raspbian. That being said, I really recommend learning the BASH commands so you have a little better understanding of how git works, but also the Raspberry Pi has limited processing and the shell doesn’t take much to run. Most of the git examples you’ll see use the BASH commands, and the GUIs just put the same commands behind a button and then most just run the shell anyway.
I’m going to really simplify what you new RPi hackers need to know. Some of the features are meant for teams of developers who automatically want to push code to a cloud computing environment and run all kinds of tests, while you’re just trying to get an LED to light up when you push a button. Bottom line–you won’t need a lot of what GH and BB offer for a long, long while, if ever.
First and foremost is understanding a little code management strategy. Both GH and BB offer unlimited repositories, so make use of that. At its most basic, think of a repository as a main folder for your work. If you get the LED to light up, and want to now try making a buzzer sound, you wouldn’t put those in the same folder on your RPi–you should separate the two. You’d then make a corresponding separate repository (“repo” for short) for each project in GH or BB. To get started you might copy the code from the LED project into your buzzer project, and that’s cool, but you’d still keep the two things separate.
When you need a new repo, there are two ways to get started. If you’ve already started your project, your workflow would look like this (and I’ll explain a little more below):
- Create the remote repo on GH/BB (called “remote” because it’s not on your machine)
- On your device, use “git init” to create the local repo
- Link your local and remote repos
- add/commit/push your files
If you haven’t started a project yet, your workflow would look like this:
- Create the remote repo
- “git clone” to your device to create the local repo
- do your work
- add/commit/push your files
Either way, once you have your repo set up and first code committed, everything works the same. Neither way of getting started is “wrong”, both exist because sometimes we code first and sometimes we repo first.
Also, one note, I’m kind of lazy, so when I say “GitHub” below, know that everything also applied to Bitbucket. The web pages are different between the two, but since both are based on git, all the other aspects are almost exactly the same.
Explanation – Code First
Summary–since you already have a folder on your device full of code, we need to turn it into a local repository. This is called “initialization”, and uses the “git init” command. We also need to create a repository (aka folder) on GitHub, and then link the two using the “git remote add” command. Finally, you add the files you want to put under version control using “git add”, commit the changes using “git commit”, and then copy the change from your local repo to your remote repo using “git push”. You only need to “init” once per repo, and usually “remote add” once per repo, but the add/commit/push you’ll do over and over and over again, it’s how you send the different version to GitHub.
Read this to create a repo in GitHub: https://help.github.com/articles/creating-a-new-repository/. This creates that “remote folder”.
Once you have your remote repository, you’ll need to initialize (“init”) your local folder to make it a local repo, choose the files you want to add to the repo, commit those files to version control, and finally push the changes to your repo. Usually, using python on a RPi you just want to add everything in the folder (in professional development our tools–like Visual Studio or Eclipse–add a lot of other files, like settings files for color preferences and font size, we don’t share). To init your existing code to GitHub, and add/commit/push, follow the guide at https://help.github.com/articles/adding-an-existing-project-to-github-using-the-command-line/.
When you commit changes, you’re prompted to add a commit message to the set of changes. This is super-important, it’s where you make notes to yourself about what you’re doing, making it easier for you to go back to a specific version of your code. A sentence or two is pretty good, but don’t slack off. Trust me, you’ll kick yourself later if you do.