How to Download from GitHub

How to Download an App from GitHub

To download an .exe from GitHub, follow the following steps:

Step 1: find a project that made the terrible decision to host their .exe in GitHub, instead of SourceForce (where there is a nice, large, green download button right in the homepage of the project), and on top of that also decided give potential users a link directly to their GitHub repository instead of spending 20 minutes creating a simple static website freely hosted in github.io, or Neocities, or even Tumblrwith quick instruction of how to download the .exe. Bonus points if you find a project that also didn't even bother to explain how to download the .exe from GitHub on the README.md markdown file that gets displayed when you visit their GitHub repository. We'll use https://github.com/sylikc/jpegview, which is a fork of JPEGView, as an example.

Observe that this URL's path is composed of two text codes: sylikc is the username of the owner of the repository on GitHub, while jpegview is the name of the repository (of the project). In GitHub, any user can fork a repository of any other user, and so you can have multiple repositories that end in jpegview that are actually provided by different people. If you want to download JPEGView from GitHub, you must make sure sylikc is the correct source, that they didn't just fork the official repository and then put a virus in it.

Step 2: look for the "releases" link on the repository page. The design of GitHub changes from time to time, so who knows where it will be when you read this. Currently, it's in the right sidebar. It used to be at the top. Just press Ctrl+F and search for "release" and maybe you'll find it. The URL of the releases page should look like this:

https://github.com/sylikc/jpegview/releases

Alternatively, simply add /releases to the end of the URL in your address bar.

The releases page shows each "release" of the application. Release means version. In our example, the latest release as of writing is version 1.3.46, released in 7th of October, 2023. Each release contains a lot of information that nobody cares about, such as a link to the commit with a link text that is a hash (e.g. af075db). The release probably contains a changelog showing the changes of the current version, that nobody who is downloading something for the first time wants to read.

Step 3: make sure you are looking at the correct release.

Some projects may have an unstable release that appears as the first release. Make sure you're download the stable version instead of untested software.

Step 4: scroll all the way to the bottom to the "Assets" section.

Each release has an "Assets" section containing files you can actually download from GitHub. It may be collapsed (hidden). Click on it to display the assets.

Step 5: click on the correct asset to download it.

As one would expect, most releases are just a bunch of files with weird names with no description of which one you want to download, despite every release spending 5 screen heights worth of space to talk about changelogs nobody is going to read.

Which Asset File to Download?

Generally there will be a "source code" file. You do not want this.

If you are on Windows, you do not want any .tar.gz (Tarball) files. Those are for Linux users. You want a file that ends with .exe (Windows executable files), or .msi (MicroSoft Installer files). Some applications have portable versions that come in an zipped folder. In this case, you want the .zip file. If there is a .7z instead, you may need to install an application called 7zip to open it.

If you're on Linux, you want an .appimage file. Or .deb if you're on Debian-based distros (e.g. Ubuntu, Linux Mint). Or a .rpm if you're on Fedora.

The filename may also include the architecture of the CPU the executable binaries are meant for. If you choose wrong, the program won't work on your computer. A quick summary:

• x86_64 - this refers mainly to Intel 64-bit CPUs, and most likely is what you want.
• x64 - same as above.
• amd64 - this refers to AMD 64-bit CPUs, which have a different instruction set.
• arm64 - this is mainly used in mobile devices, not in PCs.
• x86, i386 - 32-bit Intel CPUs.

If your PC has more than 4 gigabytes of RAM, your CPU is 64-bit. Almost every PC nowadays has a 64-bit CPU, so unless you live in the south hemisphere (like me) and is using a computer from last decade (like I was last year), then x86_64 is what you want.

How to Download the Source Code from GitHub

As mentioned above, you can download the source code by downloading a .zip file from the assets. Many projects are developed on Linux, where .tar.gz files are more common, so the source code may be in file with such extension instead.

How to Clone a GitHub Repository with Git

To clone a GitHub repository with git, you use the git clone (insert URL here) command. This URL can be found in the GitHub repository's homepage, by clicking on the big green "Code" button.

Observation: clicking on the Code button reveals two tabs, HTTPS which only shows the URL, and GitHub CLI, which has a terminal command using GitHub's proprietary tool. The fact that there is no git clone example feels deliberate. Note that git existed before GitHub and has no relationship with it besides the fact GitHub hosts git repositories.

For example, for the sylikc's JPEGView repository, the URL would be https://github.com/sylikc/jpegview.git. So you just need to open a terminal where you want to clone the repository and type into the terminal the command:

git clone https://github.com/sylikc/jpegview.git

Done this, git will create a jpegview directory, initialize a git repository in it (i.e. git init), then pull (download) the source code from the repository URL. This method also sets the origin of the pulled branch so that you can git push to commit changes.

You can't actually push changes to a GitHub repository that you don't own. You can commit them locally, but not push them. That's why you should fork the repository in GitHub's website first, clone your fork on GitHub, push changes to your fork on GitHub, and after you're done changing things, you create a PR through GitHub to get your changes merged with the original GitHub repository.

Apps with Special Install Instructions

Some applications may have special installation instructions, specially if they're for Linux users. If you're on Ubuntu or Linux Mint and someone gave you a link to GitHub, make sure you check the README.md file (which is displayed by default), and search for "install" or "setup" before berating the developer. Then berate the developer anyway for thinking a README.md is a valid substitute for an actual manual.

On Ubuntu, Linux Mint, and other Debian-based distros, software can typically be installed by simply typing the following command in the terminal:

sudo apt-get install (package name here)

On Fedora, it's the same idea but sudo dnf install instead.

This apt-get and dnf are package managers of the respective Linux distros. Some programming languages come with their own package managers. For example, for Python, you would use pip. For Rust, you would use cargo. For Go and Zig, that's built into the language. For Javascript, you would use npm. Even Windows has its own package manager nowadays. What this means is that sometimes something you find on GitHub can be easily downloaded and installed with a single terminal command instead.

Sometimes it may be necessary to add an external repository to download the latest version of a software, or a new software that is not included in any distribution yet.

Some applications may also be available as flatpaks through flathub instead.

In rare cases an application needs to be compiled from source. Then you'll have build instructions. For example, if you go to https://gitlab.com/azelpg/azpainter, which is in Japanese, you won't be able to read anything in the page except for one section that is in common language: code. It reads:

./configure
cd build
ninja
ninja install

Note: ninja is a program used to build C programs that comes installed in various distros, it has nothing to do with the fact the software is in Japanese.

That's not even GitHub, by the way. It's GitLab. Which is essentially the same thing.

That means we can type:

git clone https://gitlab.com/azelpg/azpainter.git
cd azpainter
./configure
cd build
ninja
ninja install

And it should work.

Note: it doesn't work, actually, because the bash files have Windows line endings (\r) for some reason so you need to run dos2unix to fix it. As in dos2unix ./configure, then ./configure, then repeat it for dos2unix ./build/install.sh. Also, it would require root for ninja install to run, but it should work. I'm not going to try to sudo ninja install this because I have a feeling the code may be broken, but it should be fine to run it in Docker or in a VM.