Development: Git Clone a Project
Say you find a very interesting hack for an ESP32 microcontroller board on GitHub.
You know there are thousands of repositories on GitHub covering the ESP32 module, right?
The same goes for the Arduino platform, Python on the Raspberry Pi and various other languages/platforms.
With so much cool code out there just waiting to be put to good use, why re-invent the wheel?
Today, we’ll talk about how to grab GitHub content and put it on your local Linux notebook.
Git Linux Notebook Basics Review
Git is a file management system typically used to organize computer source code. It catalogs snapshot revisions of your files as they are developed and changed. Git also packages your code into convenient collections of files called repositories.
Sites like GitHub and GitLab are cloud-based setups that house public and private repositories. Pushing repos up on these sites makes it easy to share and manage files with others.
Setting up a repository on your local Linux notebook is trivial. Initialize the environment, add your files to the git database and commit any changes. The commands look something like the following.
rob% mkdir [new repo directory]
rob% cd [into new repo directory]
rob% git init
rob% git add [filenames]
rob% git commit
Once a repository is established on your local Linux machine, it’s fairly painless to send it up to GitHub or GitLab. We’ve covered the topic in recent articles [1] [2].
Now, let’s look at how you get somebody else’s content down to your machine. Naturally, you’ll want to respect any licensing terms.
Getting Content from a Git Repo
There are several different ways to bring content down from a GitHub repository to your Linux notebook.
You might find the file you like in a repository on GitHub and just paste/copy the text into a local file on your Linux notebook. This method would be useful for a single Arduino script that you simply want to try on your project hardware.
You might not even put it in a local git repository or text file and instead just paste it directly into the Arduino IDE edit screen. From there, you could upload and run the firmware on your Arduino, ESP8266, ESP32, or whatever. Easy.
Another way to get content down to your Linux notebook is by using a .zip file. This method is simple and works whether you’d like to track the files in a local git repository or just have the files reside in a local directory, without any git control. It is similar to setting up a git repository from scratch.
First, find your chosen repository in GitHub. Next, click on the green “Code” button. At the bottom of the drop-down look for the zip-file download link. Click the link to pull the file into your “Download” directory.
Open a terminal and make a new directory for the zip file. Copy or move the zip file into the new directory. Unzip the file.
At this point, the files are not under git control. They are simply files in a directory. You can modify them with a text editor. You can open them directly from the Arduino IDE, say if they are scripts for your project hardware.
They act just like any other normal file. Some zipped repos also have ancillary graphics files, readme files, documentation, CAD drawings, HTML code, scripts or even binary/executable files. The zip file is a snapshot of the whole repository, up on GitHub. It’s an easy way to provide a directory (repository) full of files down on your Linux notebook.
Once the files are unzipped and safely in a directory, you can go through the normal git project startup sequence to get them in the database, if you choose.
cd [into new repo directory]
git init
git add [filenames]
git commit
Zip-files are great. The git clone command works on your Linux notebook command line to pull the repository down as a bundle using a web link.
Cloning Files from GitHub
While you can download the .zip file and perform the git repository environment startup manually, the git clone command automates the whole works.
Go onto GitHub and find your repository of choice. You might put “Arduino” in the GitHub search bar. I did and came up with over 230,000 hits.
Thousands of “Arduino” repos in GitHub
For simplicity, I’ll just use one of my existing repositories as our example.
Got to the main GitHub screen and search for “drtorq/esp8266-tft”. Click on the link to the repo.
Dr. Torq’s sample esp8266-tft repo
Notice the green code button in the upper middle of the screen. If you click on that button you’ll see the drop-down box with a selection of HTTPS, SSH and github CLI. Select the HTTPS tab. Below it, you will see a link to the “drtorq/esp8266-tft” repository.
The dropdown box is under the green “code” button.
Next, copy the link and then go back to your Linux notebook terminal. cd to a directory where you want to clone the repository. Mine might be under /home/rob/parts. Use the git clone command to bring the repository down to your Linux notebook, pasting the web link in as follows.
rob% git clone https://github.com/drtorq/esp8266-tft.git
Notice in the command result listing that the new repository is named “esp8266-tft” and gives an indication of the amount of content that it contains.
Git clone command result.
You can verify the files using “ls” and compare the list to what is up in the GitHub repository.
Esp8266-tft git clone file listing on the Linux notebook.
Next, use the standard git status to check and see if everything is good in your newly created “esp8266-tft” repository.
rob% git status -v
The files are now under git control and you can edit, add and commit to your heart’s content.
That’s a Wrap
There seem to be two basic camps in GitHub. One camp uses git for hard-core, extensive source code organization, management and collaboration. The other camp uses GitHub as a kind of informal place to house projects. I fall into the latter category.
In the tech world, GitHub is a well-known, commonplace for people to go to check out your work. Git clone is a seamless way to share your and others’ work, even if the projects are relatively simple and physical computing oriented.
Contact Rob “drtorq” Reilly for consultation, speaking engagements and commissioned projects at doc@drtorq.com or 407-718-3274.
