Using Github and Git

The Piston project uses Github for open source collaboration.

Github is a website that lets people share and merge code into repositories. Each repository is like a project, and when you create an account on Github, you can create forks of repositories hosted under PistonDevelopers.

To create a fork, navigate to the project and click the "Fork" button to the upper right.

When you have created a fork, you can then clone it on your local hard drive.

Git is the protocol that controls the synchronization and merging of code between repositories. You can clone a repository by typing in the Terminal window:

git clone <url>

This command will download the repository and put it in the current folder, under the same name as the repository.

Alternatively, you can install a GUI client for Github. This lets you view the repositories belonging to your account.

Remotes

A remote is a link that points to another repository. Each local repository can have multiple remotes.

Git uses the remote origin to point to your fork of the project. To view remotes, type:

git remote

When somebody merges new code in PistonDevelopers, it is a good idea to synchronize your project with the new changes. To do this you need an upstream remote.

git remote add upstream <url>

Then, to get the new changes, you can type:

git pull --rebase upstream master

Branches

A branch is a different version of the same project, but sharing some of its history. Most repositories use a master branch.

When working on a big change, or to test something, it is common to create a branch.

git checkout -b <name>

The -b flag creates a new branch if it doesn't exist.

To go back to the master branch, type:

git checkout master

To delete a branch, you can use git branch -d <name>.

Commits

A commit is a step wise change to a project. Each commit has a title, a description and a unique number. The unique number is generated from the history and the change. One can think of a commit as "saving your work".

It is a good practice to split work into small commits when possible. For example, if there are many tasks, there could be one commit for each task. This makes it easier to track the changes for other people.

For beginners, it is recommended to use a GUI client for Github to write commit messages.

Testing other people's work

For example, Alice creates a PR and asks you to test it locally. This is how you do it:

1. Add a remote that points to to Alice's fork git remote add alice <url>.
2. Add a branch with Alice's name git checkout -b alice.
3. Get the changes from Alice's fork git pull --rebase alice master.

Sometimes the PR is pointing to another branch in Alice's fork. In this case, use git pull --rebase alice <branch>.