November 2, 2020

Working with Github

If you just want to clone something from Github, you can ignore all of this. As long as you have a git client on your machine, you are good to go.

Master or main?

In November of 2020, I went through a bunch of confusion and trouble because the imbeciles at Github decided to change the name of the default branch from master to main.

What you need to do to avoid the trouble this has caused is to not first create a repository on github then clone it onto your working machine to get started. This used to be easy and sensible, but now will get you into trouble.

Create an empty repo on github (we will call this repo "zulu" for this example. Don't have github put any files into it or do anything other than just create the repo.

Then on your system with the working copy: 

mkdir zulu
cd zulu
git init
git remote add origin [email protected]:trebisky/zulu.git
And you are in business. You can start adding files and using "git push origin master" just like nature intended.

Using Github to hold your projects

The above already has what you need to know if this isn't your first github repository.

But let's say you are new to all of this. You want to put your work on Github for the world to enjoy. First, go to Github and set up an account. It should be free, unless you want to sign up for an account with expanded storage limits or private access. If you an "ordinary joe" doing open source work, you whould be good to go with a free account.

Set up ssh keys. This is not strictly necessary, but it avoids having to supply your password over and over when you push to github using http. You will thank me later if you do this now.

Adding a new project

This is quite easy.

Login to Github. Click the "start a project" link. If you don't see the "New" button for a new project, you probably need to login or go to the "Repositories" section of your Github page.

Fill out the form this presents you with. Give the project a name and a one line description. I avoid putting a README there since I will start things off by pushing from my remote machine (see above). I always make my project public.

The next page (after it processes the form and sets up your project) gives you a bunch of help and coaching. I select SSH on to top menu and it clues me in on the URL to access the new project. They make this really easy by providing an icon on the right that you click with the mouse to copy the URL into your "clipboard". Then you can just paste it anywhere it might be needed. The URL will be something like: 

[email protected]:trebisky/zulu.git
The rest of the work takes place on the client side. I usually start with an empty directory and build things up incrementally. I start with two files (LICENSE and README.md). The README.md is written in a simple markup language (actually "md" stands for markdown) that is described somewhere on the Github site (see below). LICENSE is a copy (in my case) of the Gnu GPL version 2, circa 1991 that I like.

Another approach is to start with an existing project and in the following replace the "add ." with "add README.md" or some such and begin by controlling what files get added. Once you have a .gitignore file you can use "git add ." without chaos ensuing.

The sequence of commands for the empty directory case looks like this: 

git init
git remote add origin [email protected]:trebisky/zulu.git
git add .
git commit -m "get started"
git push -u origin master
Once this is done, you are off and rolling. You should not forget to add a .gitignore file as usual.

Markdown

The README.md files are called "markdown" in a clever pun.
Feedback? Questions? Drop me a line!

Tom's Computer Info / [email protected]