-
Notifications
You must be signed in to change notification settings - Fork 21
Basic Github usage
git is a free and open source distributed version control system. GitHub is a commercial cloud platform to interface with the GIT protocol (and some other useful features). GitHub is currently free to use, and students have the ability to get a GitHub Pro account for free as well (with additional features).
A good way to familiarize yourself with git and GitHub is to work through the no-coding-necessary "Hello, world" tutorial. To use git's many functionalities from the command line, you'll want to add an SSH key to your account.
Many Integrated Development Environments (IDE), such as PyCharm, have integrated convenient git and GitHub interfaces. You can also use GitHub Desktop as an application on your computer.
There are many excellent tutorials, blog posts, YouTube videos, etc. out there that give you a good introduction. There is also a lot of troubleshooting material available. Whatever issue you may have, likely thousands of people had the same or very similar issue before.
Here a few examples:
- "Hello, world" tutorial; a starting guide to create and edit a GitHub repository on the GitHub platform.
- Comprehensive guide of a fellow Astrophysicist; (a few years old) guide with many FAQs.
On the page of the repository you would like to check out (for example one that you created using the "Hello, world" tutorial), click on the green "Clone or download" button, select "Use SSH", and copy the shown line to your clipboard, e.g.
https://github.com/<your user name>/hello-world.git
You can now "clone" the repository from your command line:
git clone https://github.com/<your user name>/hello-world.git <local name>
where the third argument needs to be replaced by the line you copied from the repository.
The fourth argument is optional; you can specify how you would like to name the repository on your computer.
The default is to use the name of the directory, in this case hello-world.
The repository is generated in the directory from where the command line operates.
If you have already cloned a repository, and you would like to update your local copy to the most recent version, simply to
git pull
It should always do this before you start making changes - otherwise you may have to resolve conflicts.
You can now edit the files on your local copy of the repository. Adding new files is done via
git add <filename>
or if you want to add all the files in the current directory/subdirectories
git add .
This is a very convenient way if you're starting a new project or made massive changes, however be careful to not also add your 35GB datafile to the github repos! It helps to edit the .gitignore file if you want to use this option.
git really works with two repositories: one of them is your local copy, and the other one lives on the git servers.
To commit your edits to the local repository, use ``git commit'':
git commit -m "Useful description of the changes you made" [filename]
The part behind -m is for the comment that accompanies your commit.
If no -m argument is given, git will launch your favorite text editor to prompt you for a description.
Good descriptions of your edits are an important part of good coding practices!
Note that you can specify to commit only individual files through the last argument.
By default, all files that have been modified (and that are version-controlled through git) will be committed.
Pushing your changes to the repository that is hosted on the GitHub servers is done via
git push [filename]
Note that you need to have committed your changes to your local repository first!
This is fine if your project is not a team effort, and if changes are small.
For team code development, you should make changes through "pull requests" to allow code review.
One of git's most useful features are "pull requests".
Imagine that you have added a new feature to somebody's coding project, and you think it is now ready to become part of the main code - this is when you "request" that they "pull" the code from your repository into the main project.
Pull requests give you the opportunity to have somebody review the code before merging, and to discuss the changes.
To allow for parallel coding development, work can happen on several branches of the repository.
The official version lives on the main branch.
Pull requests can be made from other branches back to the main branch.
By default, the clone of a repository (which you created above), points to the main branch - which ensures that git pull always retrieves the most up-to-date version of the code.
To move the changes you made to a new branch, do
git checkout -b <new_branch_name>
(You can replace "new_branch_name" with a more descriptive name.)
To push your changes to the new branch, do
git push origin <new_branch_name>
You might have to issue some git add and git commit commands, too.
When you now go the webpage of the repository, you should see a message that you recently pushed a new branch, along with a green button "Compare and pull request".
Clicking this button will show you a comparison of the code that changed between the two branches, and give you the option to issue a pull request, along with the possibility to give a description.
This description works similar to an issue: you and the other contributors can discuss features (and problems) of the new code.
Once the issues have been resolved, the repository owner can accept the pull request.
You want to contribute to or alter repositories that you do not have control of? git has you covered! A fork is a new repository that shares code and visibility settings with the original “upstream” repository, of which you have full control over. Forks let you make changes to a project without affecting the original "upstream" repository. After you fork a repository, you can fetch updates from the upstream repository to keep your fork up to date, and you can propose changes from your fork to the upstream repository with pull requests. A fork can be owned by either a personal account or an organization.
- 'about Forks'; the official GitHub documentation.
- lenstronomy contributing guidelines; how to contribute to a well-established astronomical software project using git and GitHub.