What is GitHub?GitHub is a hub for git. Git is a so-called versioning system which means that it keeps track of changes made to the documents that it knows of. The main purpose of git and GitHub is to allow groups of people to work together on the same software project.
Because GitHub is a tool for professional- and production-quality software development, it has lots of functions and options that most people never need, and that make it complicated to use.
How to Download From GitHub?At Elektor also we publish code on GitHub and tell people to download it from there. We then often get the question “How do I download something from GitHub?” This seems like a silly question for experienced users, but it is true, you cannot just download the files you see listed in a repository. There is no save or download button, and when you click on a file, it is opened in a browser, not downloaded. If you right-click on a file and then save it, you end up with a file containing HTML code, and not the contents you expected.
Raw ModeActually, you can download a file if you open it in Raw mode first and then right-click to save it as a file, but this is, of course, undoable when there are many files.
The Green 'Clone or download' ButtonThere is an easy download button, but it is only visible when you are in the root of the repository. Once you are there things become easy: just click the green button labeled 'Clone or download'. However, you might get confused by the surprising options about cloning with HTTPS, or open it on your desktop, or download ZIP. Here you just click ‘Download ZIP’ and ignore the other stuff. You do not need to sign in or have an account.
Arduino & GitHubThe name of the file you downloaded may end with '-master' and when you unpack it, you will get a folder with the same name. Most of the time this doesn’t really matter, but it does when the download happens to be an Arduino sketch. For the Arduino IDE the name of the .INO file must be the same as the name of the folder. The solution is simple: remove the '-master' part by renaming the folder.
Usually you do not have to do this when the sketch is inside a folder nested inside the ZIP file because the nested folder will have the same name as the .INO file.
If the download is an Arduino library, then the Arduino IDE knows how to deal with it. You can import it using the “Add .ZIP library” option from the Sketch -> Include library menu.
ReleasesMany projects on GitHub are evolving continuously. If you download the ZIP file as we did before, you get a so-called ‘development snapshot’ that may not work or may not do what you expect from it.
For this reason, one tends to publish stable versions, so-called releases, that work and have been tested. These releases are often hosted on another website, for instance on the project’s official website, but GitHub also offers space for them. Check the Releases tab to see if there are any, and if there are, download the most recent one or another version or file you need.
You might also want to check the Releases tab when you are not at all interested in the source code of the project, but only in precompiled binaries to run on your platform. This is often the case when compiling the project is too complex for you or even impossible because you don’t have the tools to do it.
Cloning a RepositoryFinally, you can use the official GitHub method to download a project and that is by cloning it. To do so you may first have to install a git client on your computer. There exist clients with nice graphical user interfaces and clients that you control from the command line. In either case you will need the complete URL of the repository you want to clone. You can get it from the download button, again, but this time by copying the URL in the Clone with HTTPS box. Click the copy button next to it to do this.
Command Line (CLI) CloningIn the command line interface first navigate to the folder where you want your clone of the repository, then type the command 'git clone' and paste the URL of the repository behind it and hit enter. If all is well, the cloning process will start.
git clone https://github.com/ElektorLabs/180468-ESP32-Weatherstation.git