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 Waterhackweek with your own GitHub account.

Git Installation

  • Windows
    • Install Git for Windows from this link. For more setup details follow these instructions
  • Mac OS
  • Linux (Debian): 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, but for Windows you can follow the instructions in this link to set it up. Test your installation by opening a terminal and running nano --version. If it works you can link your git configuration with nano:

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 Waterhackweek 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 Waterhackweek organization, https://github.com/waterhackweek

New Repo

Click New and follow the steps: check yes to create a README.md file.

  • Format project name as whw20-proj-myprojectname (you can change the name later), where myprojectname is 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 bell notifications 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 Waterhackweek work (cd path_to_Waterhackweek).

git clone https://github.com/waterhackweek/whw20-proj-myprojectname.git

This will create a new folder called whw20-proj-myprojectname. Navigate to the new folder, whw20-proj-myprojectname.

3. Update the README with your name

Open the 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 the your repository. Pay attention to the colors. To see the changes in the files run git diff.

4. Update your local repository (local clone) with the changes of your collaborators

git pull origin master

Remember 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.

Centralized Workflow

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

git status

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 master

You can continue working on as usual.

Remember to pull often and push small changes ...

... to avoid messing with complicatd 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.

Some merge conflicts can be avoided by working with forks (using a "forking git workflow) instead of directly pushing to the repo.

Forking Git Workflow

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)
  • Go to your local repo and rename your origin to point to the fork:
git remote rm origin
git remote add origin https://github.com/myghusername/whw20-proj-ProjectName.git
  • Add a new remote to talk to the main repo:
git remote add upstream https://github.com/waterhackweek/whw20-proj-ProjectName.git

From now on you will push to origin, but you pull from upstream.

Warning

"Make sure your origin contains your github username, and upstream contains the Waterhackweek name."

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 master

Note

They appear on your fork, but not on the main repo.

Submit a pull request by clicking New pull request:

New PR

  • Explain what changes you have made.
  • Assign somebody for review.
  • Reviewer: look through changes in the files
  • Approve PR or ask for more changes.

Note

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.

BasicForkWorkflow

Troubleshooting

Deleting files

git rm filename.txt
rm filename.txt

Note

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

Note

Your files in the local repo will be still 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: