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
Open in DesktopIn the desktop interface, from the menu select ‘File’ -> ‘Clone repository…’, browse to the destination folder and paste the URL you copied before in the box labeled ‘Repository URL’, then click Clone.
Cloning is Easier Than DownloadingOnce you know how to do it, then cloning is probably easier than downloading. You don’t have to unpack anything and you can clone directly into the folder where you want it. And you don’t get the ‘-master’ added to the repository’s name either.
Part 2: Share Your Work on GitHub
Why Publish on GitHub?Well, there are several reasons:
- Share your work so other people can profit from the hard work you did;
- Back-up your work. Once it is in the cloud it will be more difficult to lose;
- Work together with other people on a project. This is actually the main reason why GitHub exists.
License Your WorkWhen you make something public, you must specify how other people can use it. This means that you must choose a license for your project. There are all sorts of licenses, and it is up to you to choose the one that suits you best. Common licenses are MIT, LGPL or Creative Commons Attribution Share-Alike. Licensing is a complicated matter, so you may want to study this subject a bit before proceeding. Simply saying “you can do whatever you want with this” is not good enough.
You can choose a license when you create the repository, or you can add license statements to your files now.
Organize Your WorkBefore you publish anything on GitHub you must first organise your material. Someone who will download or clone your stuff expects that all the files are in the right places and that it will run straight out of the box. Once your project is on GitHub you don’t want to make important changes to its structure as this makes things confusing for your users. This means that you will have to think carefully about how you organize your project.
Of course, you can put everything in the same folder, and this is fine for small projects, but it quickly becomes a mess when a project grows bigger. So, if needed, reorganize your project using folders to keep things together that belong together. There are no rules for this, only common practice. Look around on GitHub to see how other people organize their stuff.
Test Your WorkOnce you project is properly organized, you must make sure that it still works. The idea of a versioning system like GitHub is that only working and preferable thoroughly tested projects are published. Work in progress remains on your computer until it is ready for publishing. Therefore, build your project and test it.
Write a ReadmeThen you must write a README.MD document. This is just a plain text document that lives in the root of your repository and that will function as a kind of homepage for it. The name of the file must be README.MD for this to work (MD stands for Markdown).
In this document you write down clear instructions for building your project and how to use it. Also explain what the purpose is of the project. Strangely enough, people often forget to do this, making it hard for visitors to figure out what a project is about. Put yourself in the position of a potential user.
Note that you can skip this step as GitHub lets you create the README file when you create the repository, but it is good practice to create the file first.
Once your project is organized on your computer, and tested, and it has a README.MD file, you can proceed to the publishing stage. In order to publish on GitHub, you must have an account.
Creating a repository is very easy:
- Clicking the ‘Plus’ icon next to your profile avatar, then select ‘New repository’;
- Enter a name for your repository;
- Enter a short but clear description;
- Choose ‘public’ if you want your project to be visible to the whole world. If you don’t want this, choose ‘private’. Note that there are some limitations for private repositories;
- Check ‘Initialize this repository with a README’ if you didn't create one already;
- Choose a license. Click the little ‘i’ to open a page with more information about licenses;
- Click ‘Create repository’.
Add your files to the ‘repo’This is surprisingly easy as you can just drag and drop your files in the repository without having to type hard-to-remember commands in a terminal window. So, open the repository on your computer in a file explorer, select everything and drag and drop it on the GitHub page.
Wait for GitHub to transfer the files and then enter a commit comment. Usually this comment explains the reason for this commit. It is applied to all the files that are part of the commit or update. The last commit comment will be visible. In the large box you can enter more detailed information about the reasons for this update.
Click ‘Commit changes’ to finalize the commit.
Two Ways to Manage the Repo1. Continue with drag & drop to add files or to update them. You can even edit and delte files directly online. GitHub will be the master copy of the repository. The local and remote repositories are not synchronised, and git commands entered in a terminal won’t work.
2. Clone the GitHub repository to a new location on your local drive. Do this using the git clone command (see above). Now a hidden folder with the name ‘.git’ is created. This folder provides the synchronisation between your local repository and the master on GitHub. And it allows you to use git commands to interact with the repository.
This is the preferred way of doing things, but it requires knowledge of how to use git.
You can always use drag and drop, but it will break the synchronisation between the local and remote repositories. To restore the synchronisation, you must clone again.
Good guides for git commands can be found online.