Git Setup and Basics#
About Git and GitHub#
Git is a popular version control system that is the foundation of most open source software development. You are not required to be a Git pro in advance of this event, but come prepared to learn a lot about it! GitHub is a hosting service for Git repositories, enabling us to share code across teams in a web environment.
We will use Git and GitHub for collaborative work. Be sure to arrive at OceanHackWeek with your own GitHub account.
Download the git installer and run it.
sudo apt install git-all
To test, open the terminal (on Windows, Git Bash) and setup your username and email:
git config --global user.name "your username" git config --global user.email "your email"
Getting started with Bash terminal#
During the hackweek it will be useful to know how to navigate between files from the command line. If you are not familiar with the linux shell commands, you can review the first three sections of this Software Carpentry Shell Novice lesson. On Windows, use the Git Bash terminal to run these commands.
Terminal (command line) text editor#
When working on the command line (the terminal or shell), it is often handy to modify file content directly from there. For that you can use a command line editor such as nano. On Mac and Linux it is usually pre-installed, and on Windows it is installed when you install Git (see here for more information about nano and its configuration). Test your installation by opening a terminal and running
nano --version. If it works you can link your git configuration with
git config --global core.editor "nano -w"
Git steps and workflows#
“Centralized vs Fork-Clone workflows”
Steps 1-5 focus on the Git “centralized workflow”. We present it here as an illustration, but the workflow we recommend for use in OceanHackWeek is the Git Fork - Clone workflow, discussed in Step 6.
1. Create a project repository#
On your own or someone in your project group (preferably one who has never done it before), create a repository for the project under the
New and follow the steps: check yes to create a
Format project name as
ohw23-proj-myprojectname(you can change the name later), where
myprojectnameis a brief name for your project
Invite others to the repo:
Settings -> Collaborators
Note to collaborators: you will receive an invitation to your email associated with github.com. If you cannnot find it look for the
bellnotifications on the top right of the website.
2. Clone the repository#
Each participant should clone the repository so they have their copy on their JupyterHub account space (and locally in the participant’s computer, if desired). Navigate through the terminal to the folder where you want to keep OceanHackWeek work (
git clone https://github.com/oceanhackweek/ohw23-proj-myprojectname.git
This will create a new folder called
ohw23-proj-myprojectname. Navigate (
cd) to this new folder.
3. Update the README with your name#
README.md file with your favorite editor and create a new section header. Under this section add your name. Then add this change, commit it to the local repository, and push it so that it appears on the
origin GitHub repository.
git add README.md git commit -m "Adding new name to README.md" git push origin
Make sure your change appears online.
“Remember to run:”
git status to observe the changes made into your repository. Pay attention to the colors. To see the changes in the files run
4. Update your local repository (local clone) with the changes of your collaborators#
git pull origin main
“Short names for repositories:”
origin is just a short name of the web address of the repository.”
To see what is hidden in origin:
git remote -v
To continue practicing these steps, make more changes to the title and the description of the project.
Ran into a problem?
When working with several people sometimes you
Cannot push because changes have been made that have not been incorporated: need to first pull
When pulling you arrive into a merge conflict: need to resolve the conflict manually
5. Resolving the merge conflict#
You will see the file(s) which caused the merge conflict in green.
Open it and detect the conflict by the special format:
<<<<<<< HEAD my text ======= somebody else's text >>>>>>> 35ab35436
Decide which changes you want to keep, and modify the file so it looks as you wish directly from the editor. Remove the unnecessary characters. Add, commit and push the changes.
git add README.md git commit -m "resolving merge conflict" git push origin main
You can continue working on as usual.
“Remember to pull often and push small changes …”
… to avoid messing with complicated merges and keep your repo up-to-date.
6. Avoiding problems: forking workflow#
So far you collaborated using what is called a “centralized git workflow”: i.e. every collaborator makes directly changes to the repo.
Many merge conflicts can be avoided by working with forks (using a “forking git workflow) instead of directly pushing to the repo.
“Forking Git Workflow”
This is the workflow covered in the OHW20 pre-hackweek presentation on 2020-8-6. The presentation pdf is here, and the recording is here; this workflow is the one recommended for use in OHW23. Here’s an excellent guide to the Forking Git Workflow: Step-by-step guide to contributing on GitHub
Forks are public copies of the main repo, from which you can submit changes to the main repo.
Sync your local repo with the public one
Fork the public repo (click on the Fork button)
Note it looks the same but the web address contains your username
Go to your local repo and rename your
originto point to the fork:
git remote rm origin git remote add origin https://github.com/myghusername/ohw23-proj-myprojectname.git
Add a new remote to talk to the main repo:
git remote add upstream https://github.com/oceanhackweek/ohw23-proj-myprojectname.git
From now on you will push to
origin, but pull from
Make sure your
origin contains your github username, and upstream contains the
Github has a handy command line tool
gh. If you fork a repo and use the
gh command shown on the page to clone the repo, it will set
origin appropriately for you.
Submitting changes via a pull request#
Make some changes to a file and commit and publish them.
git add README.md git commit -m "more changes" git push origin main
They appear on your fork, but not on the main repo.
Submit a pull request by clicking
New pull request:
Explain what changes you have made.
Assign somebody for review.
Reviewer: look through changes in the files
Approve PR or ask for more changes.
While your pull request is pending, any change you push to the fork will become a part of the request. This is useful if you are asked to make small changes before your PR is accepted.
In general we encourage github users to submit changes to the main repo through pull requests, but direct push is still a viable workflow for small projects when participants work on the same documents.
git rm filename.txt rm filename.txt
git rm just removes the file from git, to delete the file completely use the bash
rm command after that.
Reverting to the previous commit#
git revert HEAD
Your files in the local repo will still be there.
References and Resources#
Git and GitHub are very powerful tools but no doubt the learning curve is steep. Learning is an iterative process so below we list some resources which can help you be better prepared:
OceanHackWeek (OHW) tutorials
git-novice - Software Carpentry Lesson (3 hours with exercises)
An excellent guide to the Forking Git Workflow: Step-by-step guide to contributing on GitHub
What is GitHub? (3:45 min)
GitHub Learning Lab: practice with a bot! (On your own pace)
ICESAT-2HackWeek intro-jupyter-git repo, with several notebooks going into a lot of detail.