-
-
Notifications
You must be signed in to change notification settings - Fork 234
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.
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
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>.
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.
For example, Alice creates a PR and asks you to test it locally. This is how you do it:
- Add a remote that points to to Alice's fork
git remote add alice <url>. - Add a branch with Alice's name
git checkout -b alice. - 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>.