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)
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
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 .
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
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.
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
-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
- Ensure that everyone can access it
- Develop with other scientists
- Store the code somewhat long term
- 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
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
You will end up pushing branches to GitHub. These go to your online repo, and you'll be able to see all your branches.
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.