People often ask us how to download something from or how to publish on GitHub. Here is how.
If you use microcontrollers, play with Arduino or do other things that involve open-source software, you will most certainly have come across GitHub. It is (currently) the place for people to share source code for all sorts of open-source applications ranging from simple single-file Arduino sketches to huge cloud applications consisting of many repositories containing thousands of files, but also other things like electronics design files or simply text documents.
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 numerous functions and options that most people never need, and that make it complicated to use.
Update January 9, 2023: added DownGit for downloading parts of repositories. Update August 4, 2020: the green 'Download' button shown in the video below is now called 'Code'.
The Download button has become the Code button.
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 Mode
Actually, 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 'Code' Button
There 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 'Code' (this buttons used to be called '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 & GitHub
The 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.
Releases
Many 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 Repository
Finally, 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) Cloning
In 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.
In 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 Downloading
Once 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.
Download Just One Folder?
Some repositories are huge, and you may be interested in only a part of it. There are ways to do this. Here are two methods.
Using DownGit DownGit is a website that lets you download a part of a repository. It is really simple to use. All you have to do is paste the URL of the part (subfolder or file) you are interested in in the URL box on the DownGit page and click the 'Create Download Link' button. The page will grab the files for you and sends them to you as a convenient ZIP file.
Using SVN (subversion)
Install an SVN command line client, for instance SlikSVN;
From the green download button, as explained above, copy the repository's URL, the one that ends with '.git';
Add '/trunk/' at the end;
On GitHub navigate to the folder you are interested in and copy its URL;
Copy the part after '/master/' and paste it to the .git URL that now ends with '/trunk/';
Execute the SVN 'export' command with this combined URL. This may take up to 30 seconds before something starts happening.
Install the SVN client if you don't have one already
Get the repository's URL: https://github.com/thebiguno/microcontroller-projects.git
Add '/trunk' to it: https://github.com/thebiguno/microcontroller-projects.git/trunk/
Copy the folder's URL: https://github.com/thebiguno/microcontroller-projects/tree/master/projects/led_clock
Get the part after '/master/' ('projects/led_clock') and add it to the '.git' URL: https://github.com/thebiguno/microcontroller-projects.git/trunk/projects/led_clock
In a command line interface (CLI) do SVN 'export' and wait for it to complete (will take some time)
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 Work
When 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 Work
Before 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 Work
Once 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 Readme
Then 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’.
You will now see an empty repository. If you chose a license, there will be a license file in it; if you created the readme on the fly, it will be in there too.
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 Repo
1. Continue with drag & drop to add files or to update them. You can even edit and delete 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.
Always keep in mind that what is on GitHub is supposed to work. So only update files when everything has been tested first. If your commit breaks the project, then, to cite a famous American president: “you’re fired!”
Deleting a Repository
After your first experiments you might want to delete the repository from GitHub. This is possible, of course, but requires several clicks and a bit of scrolling and there are some security hurdles to take. It starts by clicking the settings button when you are in the root of the repository, and then scroll down all the way to the 'Danger Zone'.
Discussie (2 opmerking(en))