Using Git And Github

Contributing to a project

These instructions are designated for a developer who wants to make contribution to the Giraph project.

External Git Repository

A cloned repo of the Git repo at Apache: https://git-wip-us.apache.org/repos/asf/giraph.git, will be used as a backup storage and for pull requests, but not for collaboration with the Giraph team or committers.

Step 1: Create an account On Github

https://github.com/signup/free

Step 2: Create a repo on Github

(see tutorial on https://help.github.com/articles/create-a-repo)

Step 3: Clone the Git repository at Apache

$ git clone https://git-wip-us.apache.org/repos/asf/giraph.git
# Make a clone of the external repository to a local directory

Step 4: Push the local cloned repository to GitHub

Using the "mirror" option, which ensures that all references (i.e. branches, tags, etc.) are copied to the imported repository.

Here are the commands written out:

# In this example, we use 
# a GitHub account named username to transfer giraph

$ cd giraph
$ git push --mirror https://github.com/username/giraph.git
# Push mirror to new GitHub repository

$ cd ..
$ rm -rf giraph
# Remove temporary local repository

Step 5: Clone the new source repo on Github

To work on the project, clone it to your local machine.

Run the following code:

 
$ git clone https://github.com/username/giraph.git
# Clones your fork of the repository into the current directory in terminal

Step 4: Configure remotes

When a repository is cloned, it has a default remote called "origin" which points to your fork on Github, not the original repository it was forked from. Go into the folder containing the cloned project and add the "upstream" remote so you can pull changes from the original repository.

$ cd giraph
# Changes the active directory in the prompt to the newly cloned "giraph" directory
$ git remote add upstream https://git-wip-us.apache.org/repos/asf/giraph.git
# Assigns the original repository to a remote called "upstream"
$ git fetch upstream
# Pulls in changes not present in your local repository, without modifying your files

Step 5: Push commits

Changes to the cloned project on the local machine can be pushed to your cloned repository on Github

$ git status
# Show files or folders to commit
$ git add [specify new file(s) to be committed]
$ git commit -m "comment"
$ git push
# Pushes commits to your remote repository stored on GitHub

Step 6: Pull in upstream changes

If the original repository you cloned your project from gets updated, you can add those updates to your Github clone by running the following code:

$ git fetch upstream
# Fetches any new changes from the original repository
$ git merge upstream/master
# Merges any changes fetched into your working files

Internal Git Repository

A private fork of the Giraph repo: https://github.com/apache/giraph, will be used as a backup storage and for pull requests, but not for collaboration with the Giraph team or committers.

Step 1: Create an account On Github

https://github.com/signup/free

Step 2: Fork the Giraph repository on Github

To get the code, fork this project and click the "Fork" button. This will create on the Github site only. (see tutorial: http://help.github.com/fork-a-repo).

Step 3: Clone your fork

To work on the project, clone it to your local machine.

Run the following code:

 
$ git clone https://github.com/username/giraph.git
# Clones your fork of the repository into the current directory in terminal

Step 4: Configure remotes

When a repository is cloned, it has a default remote called "origin" which points to your fork on Github, not the original repository it was forked from. Go into the folder containing the cloned project and add the "upstream" remote so you can pull changes from the original repository.

$ cd giraph
# Changes the active directory in the prompt to the newly cloned "giraph" directory
$ git remote add upstream https://github.com/apache/giraph.git
# Assigns the original repository to a remote called "upstream"
$ git fetch upstream
# Pulls in changes not present in your local repository, without modifying your files

Step 5: Push commits

Changes to the cloned project on the local machine can be pushed to your forked repository on Github

$ git push origin master
# Pushes commits to your remote repository stored on GitHub

Step 6: Pull in upstream changes

If the original repository you forked your project from gets updated, you can add those updates to your fork by running the following code:

$ git fetch upstream
# Fetches any new changes from the original repository
$ git merge upstream/master
# Merges any changes fetched into your working files

Step 7: Fetch all branches on remote repository

$ git fetch --all

Step 8: List all available branches

$ git branch -a

The currently checked out branch is highlighted with an asterisk. The master branch is the latest development branch

References:

1 https://help.github.com/articles/create-a-repo
2 http://gitref.org/remotes/