Last time I showed you how to create a local Git repository around a PCB project. This alone provides you with local backups, helping you not to lose changes you make to your files, and you’ll always be able to review your project history as it develops.
However, the most important part of Git’s usefulness is the ability to upload our creations to one of the various Git online repository hosting services, and keep them updated at all times with a single shell command. I’d like to show you how to upload your project to GitHub and GitLab, in particular!
a summary
First, let’s summarize what goes into creating the repository. Here’s a series of commands you can refer to – these commands were explained in the last article, so they’re here in case you need a cheat sheet.
# setting up identity - these are public, and can be fake git config --global user.name "John Doe" git config --global user.email [email protected] # initializing a repository git init . git branch -M main # before your first commit, you add your .gitignore file # then, add files as needed - use 'git status' to check in git add board.kicad_pcb [...] git add README.md # or, given proper .gitignore, you can just do this: git add . # put your added changes into a commit git commit # an editor will open to write your commit message
What if you don’t have a PCB project on hand? Here is a repository with the Jolly Wrencher SAO board that you can download as a .zip archive through the GitHub interface. It’s actually a repository – if you want to test these commands but don’t have a PCB project on hand, you can freely push this repository into your GitHub or GitLab account as a testing exercise! If you want to start over and practice the Create Repository part, just delete the file .git The directory is in the root of the project.
What is the difference?
GitHub and GitLab both act as a front end to your repository. They also provide an extra place to dump your code – you can also use a flash drive or a server with an SSH account. But hosting gives you a web interface where other people can look at your code and its README so they know if your code is of interest to them, ask you questions, share their code changes with you, and download any additional related files (such as gerbers) you may have uploaded it, and done countless other useful things. You don’t need to use any of these features – you can disable them all, but they are there once they prove useful to you.
GitHub is the most well-known platform, and it has pioneered in many aspects. A large portion of small software and hardware hacks happen on GitHub, and there will also be plenty of repositories that you might find yourself interested in contributing to. There are plenty of tutorials that work with GitHub, and fun tools like the GitHub UI command line have you covered.
GitLab is a lesser known but no less useful platform that you can use for code, PCBs, and documents, and it has important advantages over GitHub. First of all, GitLab itself is completely open source, so you can host it yourself, and many do. It is not the only self-hosted service, but it is one of the most prominent and complete. Just like with WordPress being a software suite and platform, you don’t have to host it yourself. If you want a place to host your repositories, you can go to gitlab.com And register an account, just like people do with GitHub.
There are a variety of frontends for hosting repositories that can be accessed online – Gitea is another interface that you will run into every now and then and you can easily self-host, and there are a plethora of other interfaces that people have used over the years. Knowing how two of these prominent interfaces work, what they have in common and how they differ, you’ll quickly find your way around any other.
Registration on both sites is somewhat similar. GitHub’s subscription model is pretty flashy – they’ve obviously invested a great deal of money and effort into making it, but it’s not clear if this is the right choice. The Gitlab registration process is quieter and generally similar to what you would expect from a regular website. At certain points, they will both ask you to confirm your email address – after doing that, your account will be ready to use.
Create Warehouse
On both platforms, you will need to create and register a repository on the platform first. You can’t just upload code to your account from the command line on a whim – the corresponding repository must be created on the platform side before you can upload to it. There are command line tools to help with the “build” step, fortunately!
Github and Gitlab operations are similar, each providing some quality of life features. In both, the “New Repository” button is quite straightforward, and by clicking on it, you are invited to enter the name of the repository – on GitHub, which is also an optional description. In GitLab, you’ll want to use the “Create empty project” option. Options to add a file READMEAnd the .gitignore A license can be useful. If you don’t have some of these in the repository, feel free to check these boxes or press those buttons; Don’t check any of them out if you’re using Jolly Wrencher files as training, unless you’re looking for a hard mod on your Git learning journey.
GitHub and GitLab both provide you with a set of command line instructions on how to proceed with loading your local repository. We describe this instructable about adding a very abstract README and making the first commit. Getting a README in a PCB project folder is a good practice, although perhaps having a blank line or a single line is a disappointment for repository viewers. If you don’t care about people looking at your repository, don’t worry about it.
Important lines are git remote And the git push ones with git branch being useful. These are where the loading magic happens. git remote is the command you use to manage non-local Git mirrors known as Git for a specific repository, and git push It is the command you use to send changes from your repository to a mirror. git branch -M main You rename your base branch to ‘main’ – most tutorials currently use ‘main’, which will make your life a little easier.
Short turn for authentication
Before we can push, we need to sort the authentication – as in, how do we show the platform that the person executing this command line is someone authorized to upload data to this repository. The two platforms achieve this in different ways. For GitHub, the usual combination of login plus password will not work – since it is a platform where people share code used by millions of people, mostly literally and without verifications, they have hardened their defenses, putting more responsibility on our shoulders.
You have two ways when it comes to uploading to GitHub. Either you go to the HTTPS route, and then generate a token that you use in place of your password. Instead, you go to the SSH path, which means that you generate and upload a public key that you use for authentication. Both are safe options and are of paramount importance if someone else is counting on your code to be free of malware. However, one could argue that they are overloading a few PCBs. Both options are something you can do once and forget, GitHub has short tutorials to help you set up one of these methods, and tools like GitHub Desktop or GitHub CLI take care of them for you.
However, GitLab doesn’t mind letting you upload with the same password you used to create your account. There are security advantages to using keys instead of passwords – they’re not mandatory, they can be easily revoked, and hacking your SSH key doesn’t put your entire account at risk. Additionally, you can (and should) protect your keys with a passphrase. There’s also the undeniable convenience of using just a password – you don’t have to store a token or register an SSH key for every device you want to work from.
Nice SSH keys. To use Your Computer, it’s nicer than password authentication in many ways. If you’re on Linux, you’ll basically get SSH keys for free, and I’d recommend learning how to use them – you’re probably already using an SSH key on your Raspberry Pi; The same goes for macOS. On Windows there are tutorials on how to create an SSH key that you can use with Git.
Finally, the download
After sorting the authentication method, you should be ready to upload your token. Let’s point your local Git repository configuration to the right place. It will tell Git that this local repository corresponds to a remote repository, colloquially referred to as “remote”.
If you have one remote, it’s usually called “origin” – that’s just a convention, you can call it whatever; You can have multiple remotes, but if you call it “original”, the compatibility of the tutorial will be better again. GitHub and GitLab will both give you a URL to use as a remote URL, depending on whether you choose HTTPS or SSH authentication – GitLab won’t give you SSH URLs until you upload an SSH key, while GitHub will happily give you URLs but you won’t be able to use them.
Whichever you choose, run the command git remote add origin YOUR_URL, replacing YOUR_URL with the URL you are using of course. This tells your Git repository where to upload, and now you’re one command away from copying your files online. At first, this will be the order git push -u origin main – For all subsequent batches, it will be as short as git push.
If you decide to add a README, license file, or file .gitignore file, you’ll actually want to do git pull Before git push. This is because these files have been added by GitHub/GitLab as separate commits in your repository, and they don’t exist in your local repository yet, which means you have two repositories with dissimilar commit history. In this case, your repository will absorb the initial changes and save them on top of your file.
After making the first batch in your repository, you can now open the GitHub/GitLab repository page in the browser and see the uploaded files there. Anytime you then make and implement changes, their sync to your PC is one git push far.
A few reminders
If you press then use commit --amend To fix things, you’ll want to git push --force, since it was possible to modify the last commit, recreate the hash and make it incompatible with the last commit you just pushed into the remote repository. However, doing a push with force is generally unwise, and it’s best to make an additional commitment afterward. This is mostly convenient if you are working with others, because they may have pulled out of your repository between pushing the original and modified commit.
push --forcebut a different solution is usually required.If you ever need to download your repository to a different computer, the command you can use is git clone with the following URL. The ‘ZIP Download’ option is viable, but you don’t always have an easy-to-use web user interface – for example, on a headless installation, like a Raspberry Pi you might set up with some helpful self-written or provided software.
For me personally, because I use the command line heavily, I find that git clone To be a faster option compared to ZIP download. If the repository is public, using an HTTPS URL to copy it doesn’t need any authentication – in fact, on GitHub and GitLab you can git clone The URL of the repository as you see it in your browser. try out git clone https://github.com/CRImier/jolly_wrencher_sao for example.
Shared for everyone to learn from
GitHub and GitLab are both good options for a hardware hacker looking to keep some PCB projects online, and you can always create a private server if needed. The upload process can be a little involved for setup, but once you have it set up, you are three orders away from getting the latest PCB design available online and available to all interested. Next time I’d like to show how two or more hackers can collaborate on PCB projects using Git!