Git is powerful. Git is fully featured. Git is a pain in the butt to understand.

You have better things to do than to understand git.

What git is: It’s a version control system. It allows you to save projects as they evolve, and you can go back to earlier versions if needed. It facilitates working on new features without messing up the older version, and collaboration between multiple people on the same project.

But for your purposes, maybe little to none of that matters much. What you care about is that git relates to GitHub, and GitHub gives you a way of making your project available to other people.

How, though?

GitHub. And GitLab.

Let’s start at the GitHub end… or not. Right now I’m not that much a fan of GitHub. For one thing, GitHub (GH) is owned by Microsoft, and, well, Microsoft, enough said. For another, they’ve bought into the AI hype with their Copilot product. Which, I don’t know, might be useful in some cases, but there are all sorts of complaints about Copilot violating the intellectual property rights of GitHub users. For a third, GH is now requiring two factor authentication at least for some users, which amounts to requiring handing over your phone number to Microsoft.

For a fourth thing, GH heavily encourages you to use open source licensing on your projects, which I think is great, except… GH itself is closed source.

I’ve recently switched over to GitLab (GL). There’s no AI, no compulsory 2FA, it is open source, and its owners seem to be fairly benign. Using GitLab is a lot like using GitHub, so switching between them is pretty easy. A significant difference is that you can make some use of GitHub without installing or knowing anything about git. GitLab pretty much requires using git.

There are other options too: Codeberg is one. I haven’t used them though.

One thing about these sites: They’re really intended for software. I’m using GL for KiCad hardware designs, and it’s not a perfect fit. But it works okay.

To use GH or GL you first open a (free) account. Simple enough, just go to the site and walk through the signup procedure.

Creating a repository

Then you create repositories. A repository (or repo) is where you put a collection of computer files relating to a project. Or several projects, but here’s where I have my one piece of boldface advice:

Don’t put more than one project in a repository.

It’s tempting to do so, just have one repo with separate folders for each of your 29 synth module projects. The problem is, other users basically cannot then download just the files for one project. Pretty much you can download one file at a time, or the whole repo — not anything in between, including one folder.

So be kind to your friends. One project, one repo. Like this:


On GitHub:

  1. From your GitHub dashboard. click on the + button at the upper right.
  2. From the dropdown, select New repository. Note, not New project. On GL, repos and projects are the same thing. On GH… who knows what a project is. I don’t. Create a repo.
  3. Fill in the fields on the page that comes up. Give a short snappy name to the repo, 3340vco maybe. Put an elevator pitch description in the Description field.
    You can select Public or Private. You can start with Private and make it Public later. There are features you can’t use on private repos unless you pay for a GitHub Pro account, but those features are unlikely to be anything you care about right now.
    You can add a README file or a .gitignore file here, but I’d say don’t, you’ll do that later. You can choose a license; they give you a bunch of open source licenses to choose from. I’m not going to tell you how to pick one, that’s the subject of another tutorial.
  4. Click the “Create repository” button.

There, you’ve created a repo.

On GitLab:

It’s much the same. The + button is on the upper left, and you choose New project/repository. Then click the Create blank project button. Give it a name, ignore the Project slug field and the Project deployment target dropdown. Pick Public or Private. As far as I know, on GL private repos do not have any special limitations on them. Uncheck the README thing. Click Create project.


Now you need to put files and folders in your repo. It’s probably best to have a folder on your computer containing all the files relating to a single project, and nothing else. The name of the folder can be anything, though having it be the same as the name of your GH/GL repo is convenient.

You should have a README document. A text document (no, not a Microsoft Word document, a text document) in the top level of the folder; it should describe your project and tell the reader the main things they need to know about it. (It can be a Markdown document, README.md, if you want.)

Uploading files (without git)


On GitHub:

Here’s the good news: You don’t have to use git to use GH. Just upload files, done.

  1. Once you’ve created a repo, on the next page you can upload files. Select HTTPS or SSH first; pick HTTP unless you know how to use SSH, that’s outside the scope of this introduction. Then click uploading an existing file.
  2. Now you have a page where you can drag files, or click choose your files to select them with a file dialog. You can drag or select the folder containing an entire project. (Make sure you really want to upload all those files first, though.) After doing so you can drag in more files and folders.
  3. Now you can, if you want to, add a short comment at the bottom, and a more verbose explanation below that, or you can just
  4. Click Commit changes.
  5. Now your project page comes up with what you just uploaded shown as its content. Folders are just shown as folders, click on them to see the contents. If you chose a license earlier, that’s another file in your repo.
  6. There’s an Add file button near the top if you forgot something, or if you come up with something to add later.

And there you are. There’s your repo. Its URL is in your browser navigation bar, or you can right click the repo name at the top left and copy the link. Hand that link out to anyone who might be interested.

On GitLab:

For some reason, GitLab makes this a lot harder. You can only upload one file at a time. You can’t upload folders. You have to create a folder, navigate into it, and then upload files there. It’s a pain. Don’t even bother.


Uploading files (with git)

Using git is optional if you’re using GH. With GL it’s pretty much mandatory. Here’s how.

Install git. Installing git depends on your OS and the details are available elsewhere.

Now:

Open a terminal (console) window — yes, we’re using the command line here, there are graphical front ends for git but honestly for what we’re doing, the command line’s easier. Navigate into the top level of the folder you want to upload.

Enter:

git init

This tells git “I want to make this folder a git repository” — a local repository, that is; for now it has nothing to do with your remote GH or GL repo. It does not actually put anything into that repo, it just sets it up.

This would be a good time to stop and think whether you have everything in that folder you’re going to want to upload. Including that README file.

Now enter:

git add .

This tells git to set up to copy everything from this folder (and all its subfolders) into the local repo. It still hasn’t actually put anything into the repo. Don’t ask.

And now enter:

git commit -m 'Initial version'

This does put everything into the repo. The -m option is to attach an explanation of what changes you’re making — here we’re just starting out so “Initial version” is appropriate.

Now you have all your files in a local repo. Next step is to tell git where the remote repo — the one on GH or GL — is, and to “push” the contents of the local repo to that remote repo.


For GitHub:

  1. In your browser, once you’ve created a GH repo, on the next page you can upload files. Select HTTPS or SSH first; pick HTTP unless you know how to use SSH, that’s outside the scope of this introduction. Then copy the address that appears in the box to the right of that.
  2. Back on the command line, continue with:
git branch -M main
git remote add origin https://github.com/holmesrichards/foo.git
git push -u origin main

You’ll want to replace the address on the second of these commands with the one you copied above. After you enter the third command you’ll be asked for your GH username and password. (Or not, if you use the SSH address and you have the SSH keys set up.) Then it’ll upload the local repo to the remote. Go back to your browser and reload your repo page, you should see it populated with your files there.

If you added a license file when you set things up, or if for some other reason there are new files or modified files in the remote repo that didn’t come from your local repo, you can get the local repo in sync with the remote with

git pull

For GitLab:

Pretty much exactly the same. After creating a GL repo, there isn’t a box with the repo address in it but it appears among the instructions at the bottom of the page: it’ll look something like https://gitlab.com/rsholmes/foo.git. Go to step 2 above, enter those same three commands. And git pull if needed.


Modifying files

If you change a file you can put the new version on GH or GL.

Without git (on GitHub)

On GH, if you navigate to a folder, you can use the Add file button at the upper right to upload a new file or a new version of a file. In the latter case it’ll replace the old version (if you’ve uploaded it to the folder the old version was in).

With git (on GitHub or GitLab)

When you add or modify files in a folder with a git repository, you can put the new versions into the local repo and push it to the remote (GH or GL) repo as follows. Navigate to the top level folder and enter at the command line:

git add .
git commit -m 'Fix reversed pots'
git push

The comment after -m should describe the changes you’ve made. After the third command you’ll be asked for your GH or GL username and password. Then it’ll upload the changed files from the local repo to the remote.

More

Oh, there is lots more. GH and GL have all sorts of other features, git has all sorts of other features, you can go nuts with them. Or be driven nuts by them. This will get you started though.

But I’ll give you this one: If there are files you want to keep in the project folder but not have them going into the repo, create a text file in the top level folder named .gitignore. (By default, since the name starts with ., this is an invisible file — it won’t appear in a directory listing of the folder. But it’s there.) Add file names, one per line, to the file. You can use wildcards, for instance *.zip to mean all zip files. From then on any new files matching anything in .gitignore will get ignored by git. If you add foo.bar to .gitignore and foo.bar is already in the repo, it won’t get ignored, you’ll need to remove it by hand (git rm --cached foo.bar). Most of my projects have fairly substantial .gitgnore files to ignore things like KiCad temporary files and so on.

For everything else, read the manual, and good luck.

It’s fairly easy to get git confused to the point of not being able to do anything. If you’re knowledgeable and clever you can talk git down. If you’re not, you can put it out of its misery. At the command line, navigate to one folder above your project folder. Rename the project folder so it doesn’t get overwritten. It will serve as a backup for any changes you’ve made. Then enter (from the folder above the repo folder!)

git clone https://github.com/holmesrichards/foo.git

substituting the address of the remote repo. It’ll download everything into a new folder. If you’ve made changes to anything, copy the affected files from your backup to the new folder. Navigate into the new folder and do the git add / commit / push thing. Once you’re sure everything’s okay you can delete the backup folder.