View markdown source on GitHub

Contributing with GitHub via command-line

Contributors

Authors: AvatarCyril Monjeaud orcid logoAvatarBérénice Batut

Questions

Objectives

Last modification: Jul 26, 2021

Steps

1. Fork a repository

Fork from a GitHub repository

Screenshot of github repository header with watch, star and fork buttons. The fork button highlighted

Welcome on your fork repository

Screenshot for a fork of the training material repository. It shows that it is username/training-material and it has been forked from the upstream.

Welcome on your fork repository

Cartoon of two github repositories, upstream and fork. Both have branches like main, feature1 and feature2.

2. Clone your GitHub repository

Get your GitHub URL

A subset of the github interface is shown with the green code button clicked. A popup is shown with options to clone from https or ssh, open in github desktop, or download a zip file.

Clone your GitHub repository

On your terminal:

$ git clone your_fork_github_url

$ cd training-material

Clone your GitHub repository

The cartoon from before with repositories upstream and fork are now shown to exist on github, and an arrow labelled clone is drawn to a local copy that exists locally.

3. Make your changes

Create your branch

List your branches

$ git branch

  * main

a line with dots on it representing commits is labelled main has an arrow pointing to the end where there are no dots.

Create a new branch

$ git checkout -b my_new_branch

Switched to a new branch 'my_new_branch'

Make your changes

List your branches

$ git branch

	main
	* my_new_branch

The line with dots or commits is labelled main, now a different line comes out of the right most (i.e. latest) commit. this is labelled my new branch.

Make changes and commits

$ git add newfile1 newfile2 ...
$ git commit -m "my contribution"

The cartoon from above, however now there are commits shown on my new branch.

Make changes and commits

The cartoons of the three github repositories are back, upstream, fork, and local. Now local shows a new branch, my new branch.

Push your branch on your GitHub repository

$ git push origin my_new_branch

The same cartoon of the three repositories, an arrow labelled push is shown from the local copy to the fork, and now the my new branch is present in the fork, as well as locally like before.

4. The pull request

Can’t push on the original GitHub repository

The same cartoon, but now two arrows are shown between the upstream and fork repositories on github. One arrow is labelled push and has an X over it, indicating a push cannot happen. However an arrow labelled pull request is shown in colour like it can happen.

Create your pull request

Screenshot of the github interface showing a yellow popup labelled "your recently pushed branches" with my new branch shown in the list. A green button reads compare and pull request.

Select the branches and write a description

The pull request form is shown titled "Open a Pull Request", the user is busy filling out the title of the pull request. A button at the bottom reads create pull request.

Automated tests can be executed

A screenshot of the training material on github, the pull request tab is highlighted. A number of pull requests appear below, some with green check marks, some with red crosses.

Your pull request is accepted (congrats)

line with dots on it representing commits is shown, the line is labelled main as before, but now the commits from my new branch appear directly on the main branch.

Your feature is now in the original code

The same 3 repository cartoon as before, both the fork and local copy include my new branch, it looks like the author intended that upstream did too but it is missing from the graphic.

Your pull request need modifications (oops)

You have to make modifications on your branch and push it

Summary

A final version of the three repository graphic is shown, fork and upstream are on github, the local copy is local. There are several arrows: 1 fork, creating fork from upstream; 2 clone, creating local from fork; 3 push, pushing my new branch to fork; 4 pull request, starting the process of getting my new branch into upstream.

Key Points

Thank you!

This material is the result of a collaborative work. Thanks to the Galaxy Training Network and all the contributors! Galaxy Training Network This material is licensed under the Creative Commons Attribution 4.0 International License.