Basics: What is git, what is GitHub?¶

There are lots of tutorials out there about git and GitHub, and I don't think I can do better than them. Here we'll talk about the basics, and I'll show you how to do the most common things.

If you want to learn how to use git thoroughly, check out some online tutorials (e.g. here)

What is git?¶

git is a tool for version controlling. If you're making a tool or piece of software, you will want to use git to make sure, when you make changes, you can always roll back to a previous version. git is included on Mac and Linux machines. If you're in a working directory with your project in, you can start a git repository using

git init

This will make a .git directory which contains all your versioning history.

If you change a file, you can add it, meaning that git will track that file.

git add .

Will add all the files in your working directory.

When you're ready to commit the changes to these files so that a version is "saved" for you, you can use

git commit

This will prompt you for a commit message. Make sure to put something relevant and helpful. This will be visible on your GitHub page eventually, so try not to put anything incriminating.

Branches¶

git works by creating branches. You should look up some tutorials about this, but the key aspect is that branches take the work at the state you're at, and make a new copy so that you can add changes.

By default you'll be working on the main branch. You can use

git checkout -B develop

To make and checkout a new branch called develop. (-B makes a new branch and checks it out, you can omit this if you just want to switch to a new branch). Now you can make changes on this branch which won't alter main. If you want to go back to main you can use

git checkout main

If you are working on a new feature, you should be working on a new branch.

It is easy to get your wires crossed working with version control and developing lots of new features at once. The best way to work is, if you're developing a new feature, you should be on a new branch. When you're happy with the work on that branch you can merge it back into main. You can either do that with a git merge, or using a PR on GitHub.

Do I need anything else?¶

In astronomy, sometimes we have large files in our working directory that we don't want to version control. You can make sure git ignores those files by making a .gitignore file. That file should contain anything you don't want to be version controlled, e.g.

my_large_file.fits
my_large_table.csv
data/

OK then what is GitHub?¶

GitHub is a company, and online place to store your version controlled software. You can host your code there to

1. Ensure that everyone can access it
2. Develop with other scientists
3. Store the code somewhat long term
4. Eventually test your code

You can make private repos if you don't want people to see what you're working on, though mostly you'll probably want to have everything be open so people can see and learn from what you're doing.

In order to put your version controlled software online on GitHub, you'll have to first set up a remote. This is a place where you're going to send your git repo. When you start a new repo on GitHub, you'll get instructions on how to set up a remote:

git remote add origin https://github.com/christinahedges/astronomy_workflow.git

Here I have told git to add a remote named origin, and it is set to a URL. This URL is where I want my code to be stored.

If I've made changes, and commited them in git, I can send that commit to GitHub by pushing. If it's the first time you'll have to use

git push --set-upstream origin main

otherwise you can use

git push

Pushing branches¶

You will end up pushing branches to GitHub. These go to your online repo, and you'll be able to see all your branches.

What's Gist?¶

Gist is a part of GitHub where you can store single files, and it works great for storing notebooks. Gists are really useful to share around with your colleagues, because they are persistent. I also store stuff on Gist when I make a notebook that does something cool, and I don't want to lose it.