A short guide to git(hub)¶
‘Forking’ the project¶
The first step is ‘forking’ the project. A ‘fork’ is your own copy of an existing project on GitHub which lives on your GitHub account.
Installing git lfs¶
To keep the size of the repository small we use git large files storage. If you plan to add images to your contribution, you should install it. Check out this page to find the commands needed for your specific operating system.
Otherwise, simply install it from the git-lfs website, add it to your
$PATH and run the install command:
git lfs install
Downloading the project¶
Navigate to the folder in which you would like the project to be stored in your filesystem then run the following command to clone the files locally:
git clone https://github.com/<your-username>/teamtomo.github.io.git cd teamtomo
Make sure to replace
<your-username> with your GitHub username.
Create a new branch for your contribution¶
Create a new git ‘branch’ for your contribution and switch to that branch.
git checkout -b <my-contribution>
Add your file(s) and update the table of contents¶
Add your file(s) to where you think they should live within the project (take a look at the structure of the existing files for inspiration).
Once this is done, update the table of contents file
_toc.yml to include the necessary links.
Build the site locally¶
Build the site locally to check that everything looks the way it should with the following command.
jupyter-book build .
Once the site is built, a link to open the local copy of the site in your web browser will appear. Have a quick look at your contribution and if everything seems okay, move onto the next step.
Upload your contribution¶
Next you will upload your updated version of the project to your account on GitHub. First, save your changes in the current branch.
git add . git commit -m "added a new mini-tutorial on subboxing"
Then, upload your contribution with the
git push command.
git push origin <my-contribution>
Propose integration of your contribution¶
Your contribution should now be present on your GitHub page.
To propose merging your contribution into the main project,
go to your version of the project on GitHub and click the
Compare & pull request button.
Make sure that you are “Comparing across forks” and that the repository on the left is
teamtomo/teamtomo.github.io:master, while the one on the right is
Then, fill in some information about your contribution and click
Create pull request.