So you've forked a Repository and you want updates...

add-upstream.md

#tl;dr

setting up a branch to track a repo

pre: assuming you have forked a repo and cloned your fork to your computer

1. git remote add [maintainer's name] [paste URL here]
2. git fetch --all
3. git branch --track [maintainer's name]_[branch] [remote name from step 1]/[branch you want to track] At this point you may watch to checkout to your newly create branch and issue a git pull command.

Fetching updates from the maintainer's repo

1. git checkout [maintainer's name]_[branch]
2. git pull
3. git checkout master
4. git merge [maintainer's name]_[branch]

====

You've Forked Up

These are notes for someone who has forked a Repository(Repo) on Github and would like to update their forked copy with updates from the Original Repo.

For example, Let's imagine that I have cloned jQuery to my Github Account. A few days later through some notifications, jQuery has updated the Repo with new code, after some review I decide that I want this code. People new to Github/Git would delete the fork that is on their own account, then just Fork the Repo again. While this would work, it is extremely uncool (we want to be cool, right?).

The steps below outline how to set up a branch, add a new remote which points to the Original Repo, and then set up the branch to track the Original Repo, for easier and quicker updates. These steps are performed in your command-line interface and once set-up for a project, it takes at least 4 commands to update and merge in changes.

From here on out I will refer to the Original Repo as Maintainer's ....

Be Clean (step 1)

git status to ensure that you are working clean and can run the commands below. If your repo is not clean please do all the steps needed to get clean (e.g. commit, stash).

Add Original Repo's HTTPS URL (step 2)

Go to the Original Repo's Github page and get the https Clone URL. It should look something like https://github.com/jquery/jquery.git

With the URL copied to your clipboard. Run the command below in your Terminal. Here at DevLeague we prefer giving our tracking remote a name that includes the Original Repo's name followed by a _origin suffix.

Here is an example using the jQuery repo

git remote add jquery_origin https://github.com/jquery/jquery.git

command break down

git remote add [maintainer's name] [paste URL here]

After you have added a new remote

Make sure to run the fetch command, fetch goes and updates the history of a certain remote (and so much more)

using the example with jquery from above

git fetch jquery_origin

Add Tracking Branch (step 3)

before: run the command git fetch --all Our convention is to name the branch with the [maintainer's name] and a _[branch] suffix.

git branch --track jquery_master jquery_origin/master

command break down

git branch --track [maintainer's name]_[branch] [remote name from step 2]/[branch you want to track]

Before moving on...

git checkout [maintainer's name]_[branch]

Update Upstream's Master (Step 4)

Now that you've added a remote, created a new branch, and set that it (your newly created branch) to track a branch on the Original Repo. Now you can pull down changes!

run the command

git pull

You should see some changes mentioned in the Terminal.

Merge Upstream's commits (Step 5)

Now checkout to your own local working branch and merge in the changes from your branch original repo tracking branch.

Last Words

Once you have done all these steps for one repo, to get updates in the future all you need to do is Steps 4 & 5. If you have a new project, you MUST do all the steps over again to set up a tracking branch, new origin, etc.

This is great! A quick question, will I be able to do all this even after I rename the fork?

Yes, this works perfectly even after re-naming the fork.

Great thanks for this works perfectly.

hello, quick question... will this work for any github project? and if someone adds a few lines to a script that i have modified from my own fork, how will those changes be appended to my forked script changes? Thanks a ton.

@Luke-L

will this work for any github project?

Yes it will.

and if someone adds a few lines to a script that i have modified from my own fork, how will those changes be appended to my forked script changes? Thanks a ton.

So building on my example in the README.md file, Let's say there were changes from jquery_master that you want to pull into your own forked codebase, you would perform these actions in git to:

1. checkout to the branch that's tracking the original code base, e.g. git checkout jquery_master
2. you can perform the next command anywhere really, it essentially sync's up all new refs, and branches: git fetch --all documentation for git-fetch
3. Then you would pull would git pull to update your local repo with that is on the remote and from here checkout to any specific version, sha hash, etc if necessary
4. Now that you have the changes you want on your local computer, you would now checkout your local branch where you're doing work and merge jquery_master , following this example, into that branch. git checkout where-you-do-work, and then git merge jquery_master, and from there you get a clean merge or you deal with conflicts, etc.

Avoid merging your changes INTO jquery_master. You want that branch to be your own local pristine copy of the repo stored remotely.

Hope this helps!