github fork and pull request

https://help.github.com/articles/fork-a-repo/

https://help.github.com/articles/using-pull-requests/

Fork A Repo

• MAC
• WINDOWS
• LINUX

 

A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project.

Most commonly, forks are used to either propose changes to someone else's project or to use someone else's project as a starting point for your own idea.

Propose changes to someone else's project

A great example of using forks to propose changes is for bug fixes. Rather than logging an issue for a bug you've found, you can:

• Fork the repository.
• Make the fix.
• Submit a pull request to the project owner.

If the project owner likes your work, they might pull your fix into the original repository!

Use someone else's project as a starting point for your own idea.

At the heart of open source is the idea that by sharing code, we can make better, more reliable software.

In fact, when you create a repository on GitHub, you have a choice of automatically including a license file, which determines how you want your project to be shared with others.

Fork an example repository

Forking a repository is a simple two-step process. We've created a repository for you to practice with!

1. On GitHub, navigate to the octocat/Spoon-Knife repository.
2. In the top-right corner of the page, click Fork.

That's it! Now, you have a fork of the original octocat/Spoon-Knife repository.

Keep your fork synced

You might fork a project in order to propose changes to the upstream, or original, repository. In this case, it's good practice to regularly sync your fork with the upstream repository. To do this, you'll need to use Git on the command line. You can practice setting the upstream repository using the sameoctocat/Spoon-Knife repository you just forked!

Step 1: Set Up Git

If you haven't yet, you should first set up Git. Don't forget to set up authentication to GitHub from Git as well.

Step 2: Create a local clone of your fork

Right now, you have a fork of the Spoon-Knife repository, but you don't have the files in that repository on your computer. Let's create a clone of your fork locally on your computer.

1. On GitHub, navigate to your fork of the Spoon-Knife repository.

2. Under your repository name, click  to copy the clone URL for the repository.

3. Open Terminal.

4. Type git clone, and then paste the URL you copied in Step 2. It will look like this, with your GitHub username instead of YOUR-USERNAME:

   git clone https://github.com/YOUR-USERNAME/Spoon-Knife
   

5. Press Enter. Your local clone will be created.

   git clone https://github.com/YOUR-USERNAME/Spoon-Knife
   Cloning into `Spoon-Knife`...
   remote: Counting objects: 10, done.
   remote: Compressing objects: 100% (8/8), done.
   remove: Total 10 (delta 1), reused 10 (delta 1)
   Unpacking objects: 100% (10/10), done.
   

Now, you have a local copy of your fork of the Spoon-Knife repository!

Step 3: Configure Git to sync your fork with the original Spoon-Knife repository

When you fork a project in order to propose changes to the original repository, you can configure Git to pull changes from the original, or upstream, repository into the local clone of your fork.

1. On GitHub, navigate to the octocat/Spoon-Knife repository.

2. Under your repository name, click  to copy the clone URL for the repository.

3. Open Terminal.

4. Change directories to the location of the fork you cloned in Step 2: Create a local clone of your fork.

   • To go to your home directory, type just cd with no other text.
   • To list the files and folders in your current directory, type ls.
   • To go into one of your listed directories, type cd your_listed_directory.
   • To go up one directory, type cd ...

5. Type git remote -v and press Enter. You'll see the current configured remote repository for your fork.

   git remote -v
   origin  https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
   origin  https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
   

6. Type git remote add upstream, and then paste the URL you copied in Step 2 and pressEnter. It will look like this:

   git remote add upstream https://github.com/octocat/Spoon-Knife.git
   

7. To verify the new upstream repository you've specified for your fork, type git remote -vagain. You should see the URL for your fork as origin, and the URL for the original repository as upstream.

   git remote -v
   origin    https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
   origin    https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
   upstream  https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (fetch)
   upstream  https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (push)
   

Now, you can keep your fork synced with the upstream repository with a few Git commands. For more information, see "Syncing a fork."

Next Steps

The sky's the limit with the changes you can make to a fork, including:

• Creating branches: Branches allow you to build new features or test out ideas without putting your main project at risk.
• Opening pull requests: If you are hoping to contribute back to the original repository, you can send a request to the original author to pull your fork into their repository by submitting a pull request.

Using pull requests

Pull requests let you tell others about changes you've pushed to a repository on GitHub. Once a pull request is sent, interested parties can review the set of changes, discuss potential modifications, and even push follow-up commits if necessary.

This guide walks through the process of sending a hypothetical pull request and using the various code review and management tools to take the change to completion.

Before you begin

This guide assumes that you have a GitHub account, that you've forked an existing repository, and that you've pushed changes to your fork. For help with forking and pushing changes, see the Forking a Repo article.

Initiating the pull request

In the following example, Hubot has completed some work on a fork of the Octocat's Spoon-Knife repository, pushed a commit to a topic branch in his fork, and would like someone to review and merge.

Navigate to your repository with the changes you want someone else to pull and press the Pull Requestbutton.

1. Switch to your branch.

2. Click New pull request.

   

You can send pull requests from any branch or commit but we recommend that you use a topic branch. That way, you can push follow-up commits if you need to update the pull request.

Reviewing the pull request

After starting the review, you're presented with a review page where you can get a high-level overview of the changes between your branch and the repository's master branch. You can review all comments made on commits, identify which files changed, and get a list of contributors to your branch.

Changing the branch range and destination repository

By default, pull requests are based on the parent repository's default branch. In this case, thehubot/Spoon-Knife repository was forked from octocat/Spoon-Knife so the pull request is based on the master branch of the octocat/Spoon-Knife repository.

If the default parent repository isn't correct, you can change both the parent repository and the branch with the drop-down lists. You can also swap your head and base with the drop-down lists to establish diffs between reference points. References here must be branch names in your GitHub repository.

The easiest way of thinking about the branch range is this: the base branch is where you think changes should be applied, the head branch is what you would like to be applied.

When you change the base repository, you also change notifications for the pull request. Everyone that can push to the base repository will receive an email notification and see the new pull request in their dashboard the next time they sign in.

When you change any of the info in the branch range, the commit and files changed preview areas will update to show your new range.

Using the compare view, you can set up comparisons across any arbitrary timeframe.

Sending the pull request

When you're ready to submit your pull request, click Create pull request.

1. Enter a title and optional description in the discussion page. In this view, you can see the commits that are included once you send the pull request.
2. Make any necessary customizations to the commit range and review the commits and file changes.
3. Click the Create pull request button.

After you send a pull request, any commit that's pushed to your branch will be automatically added to your pull request, which is useful if you're making additional changes.

Managing pull requests

In the request dashboard, you can browse pull requests that you've sent or received. You can also view pull requests for any repository to which you have access via the Pull Requests page.

The pull request dashboard and the repository pull request list have filtering and sorting controls that you can use to narrow down the list to the pull requests you're interested in.

Reviewing proposed changes

Once you receive a pull request, you can review the proposed changes. The commits in the pull request show you what will be merged with the underlying git repository if the pull request is accepted.

You can also review the cumulative diff of all file changes across all commits, either split or unified.

Pull request discussion

After reviewing the basic description, commits, and cumulative diff, the person tasked with applying the changes may have questions or comments. Perhaps the coding style doesn't match project guideline, or the change is missing unit tests, or maybe everything looks great and some props are in order. The discussion view encourages and captures this type of discussion.

The discussion view begins with the pull request's original title and description and then chronologically lists additional activity. The following types of activity are captured as they occur:

• Comments left on the pull request itself
• Additional commits pushed to the pull request's branch
• File and line notes left on any of the commits included in the pull request's range

Pull request comments are Markdown compatible so you can embed images, use pre-formatted text blocks, and perform other formatting supported by Markdown.

Viewing long-running pull requests

When a pull request seems to linger for an extended period of time without making any progress, you may want to review it to understand what's blocking it from being resolved. You can find still-active pull requests by viewing and sorting long-running pull requests from your repository's Pull Request page.

Long-running pull requests exist for more than a month and have seen activity within the past month. This filter displays those long-running pull requests sorted by life span: the amount of time from creation to the most recent activity.

Further reading

• "Merging a Pull Request"
• "Closing a Pull Request"

• "Deleting unused branches"

• "About pull request merge squashing"