Working with Git and Github #

My notes for setting up Git and using it with Github.

Edit: A post with just the commands is available here.

Download git #

For Mac and windows, download Git from here: https://git-scm.com/downloads For Windows, if you want to do any kind of scripting in Git bash select to install all unix tools, otherwise accept the default values.

For Linux and *BSD, use a suitable package manager for your system. Example:

Fedora:
$ sudo dnf install git

Ubuntu:
$ sudo apt install git

FreeBSD:
$ sudo pkg install git

OpenBSD:
$ doas pkg_add git

Git configuration #

In a terminal, set up name and email so people know who made the changes:

$ git config --global user.name "Your Name"
$ git config --global user.email [email protected]

When working with Github, they actually recommend that you don’t use your real email to avoid leaking it online. There is an alternative address you should use instead which you can find in your Github settings. Select “emails” on the left hand side and look for “Keep my email addresses private”. There you will find the address you can use instead of your real one, while still belonging to you. Make sure to check the box if it isn’t already, and also check the box below for “Block command line pushes that expose my email”.

Next set up VS Code as the editor for Git commit messages and have Git wait until the commit message file is closed before continuing. The command “code” must be in your path and start VS Code for this to work. This should work by default on Windows and Linux. To add “code” to path on Mac, see documentation here: https://code.visualstudio.com/docs/setup/mac. In short:

1. Open VS Code
2. Press ctrl+shift+p or command+shift+p to open the command palette
3. Type "shell command" in the search
4. Select "Shell Command: Install 'code' command in PATH"
5. Restart your terminal

Then execute this command in the terminal to use VS Code by default:

$ git config --global core.editor "code --wait"

Lastly, set up how line endings should be handled to avoid problems when cooperating with people using a different system. Windows uses CR LF for line endrings, Linux/*BSD/Mac only uses LF. So if you are on Windows CR should be removed when pushing code to the repository, and added when you are pulling code from it. For the Unix variants and Mac, line endings should not be touched when pulling code from the repository, but in case the editor used has added CR, remove it when pushing to the repository.

On Windows:

> git config --global core.autocrlf true

Mac/Linux/*BSD:

$ git config --global core.autocrlf input

To view your git config:

$ git config --global -e

Set up a Git project to use with Github #

There are two ways to start a new project and use it with Github. Either initialize it locally first and then connect it to GitHub, or create it on Github first and clone it to get a local copy. If you create a new, empty repository on Github, there will be instructions on how to connect to it. If readme, gitignore or license files are added, no instructions are shown.

Initialize locally #

In a directory of your choosing, create the files you want to add to Github. At the very minimum create a readme file. From the commandline in a terminal:

$ echo "# My new repository" >> README.md
$ git init
$ git add .
$ git commit -m "Initial commit"

Create a new, empty repository on Github and note the address to it. It will have a format like this: [email protected]:<username>/<repository>.git

Then add remote address to repository and push what we’ve got so far:

$ git branch -M main
$ git remote add origin [email protected]:<username>/<repository>.git
$ git push -u origin main

When changes have been made, check the status of your repository:

$ git status

Files that are updated will have to be added and pushed.

$ git add .

Commit and then then push the changes to Github:

$ git commit
$ git push

Create and clone from Github #

If you create a repository on github.com and initialize it with some files, like the readme, gitignore or license, the easiest way to get a local copy to work with is git clone. This will create a folder with the repository name:

$ git clone [email protected]:<username>/<repository>.git

If for some reason you want the local folder to be called something other than the repository name, that can be added as a parameter:

$ git clone [email protected]:<username>/<repository>.git <new-folder-name>

A cloned repository like this has already been initialized so the git init command is not needed when working with it.

Set up SSH keys and add them to your account #

If you don’t have a suitable SSH key already, create one first:

$ ssh-keygen -t ed25519 -C "[email protected]"

The -C parameter lets you add a comment to the key, and here we set it to an email address but it can be anything. If not set it will be something like “username@DESKTOP-E7B5H2C” depending on your system. Accept the default name for the key and set a strong password for it.

Start the ssh-agent which will remember your password so you don’t have to type it every time you use SSH:

eval `ssh-agent -s`

Next add your key and password to ssh-agent:

ssh-add ~/.ssh/id_ed25519

Note that ssh-agent has to be restarted after each reboot and the key with password has to be added every time ssh-agent is started.

Finally, copy the contents of the id_ed25519.pub file and add it to Github. If you see -----BEGIN OPENSSH PRIVATE KEY----- in the file, it’s the wrong one, that one should be kept private. In Github, SSH keys are found under profile and then “SSH and GPG keys” in the menu on the left. Click “New SSH Key”, give it a title, and add they key in the “key” input field.

Working with branches #

Create a new branch locally from the point you are at now. Basically take a copy of current status:

$ git branch <new-branch-name>

List all available branches:

$ git branch -a

Switch to the new branch to make changes to it:

$ git checkout <new-branch-name>

After changes have been added and committed, push them to Github:

$ git push origin <new-branch-name>

Now the local changes are stored on Github, but there is no “connection” between the local branch and Github so it can’t easily be pulled down again. To set tracking information so they are connected:

$ git branch --set-upstream-to=origin/<new-branch-name> <new-branch-name>

Now this new branch can be modified and changes pushed as easily as for main.

Doing git push on a local branch before tracking information is set gives an error message and doesn’t work. It might be possible to combine the two commands above, git push and git branch --set-upstream with just this:

$ git push --set-upstream origin <new-branch-name>

I have not tried the above yet, I just found it somewhere but unfortunately don’t remember where any more.

In case if there has been changes on main that needs to be merged into a feature branch, make sure main is updated locally first. Then check out the feature branch and merge changes from main into it:

$ git merge main