Stay in sync with source project

While you're working on a topic branch of changes that you want to make to a repository, that repository will probably be receiving updates of its own from the original authors.

Stars & Watching

If you want to keep up-to-date with the Repository, GitHub offers a convenient way to keep track of repositories - it lets you star repositories:

The Star button and level for a repository.

You can go tohttps://github.com/starsto list out and filter all of the repositories that you have starred.

Starring is helpful if you want to keep track of certain repositories. But it's not entirely helpful if you need to actively keep up with a repositories development because you have to manually go to the stars page to view the repositories and see if they've changed.

💡 Stars & Popularity 💡

Starring can be a useful feature to help you keep track of repositories you're interested in. But stars have also turned into a means of measuring a repo's popularity.

If you'd rather not increase a repository's stars, then check out "watching" a repository. Let's look at that right now!

Watching A Repository

If you need to keep up with a project's changes and want to be notified of when things change, GitHub offers a "Watch" feature:

The Notification settings. "Watching" a repository will alert you to all activity.

If you're working on a repository quite often, then I'd suggest setting the watch setting to "Watching". This way GitHub will notify you whenever anything happens with the repository like people pushing changes to the repository, new issues being created, or comments being added to existing issues.

Including Upstream Changes

Now that you know about watching your repository let say that you're watching it and you get notified that some commits have been pushed to the original, source repository. How do you go about getting those changes into your fork of the repository? If you want to keep doing development on your fork then you'd need your fork to stay in sync with the source repository as much as possible.

Let's see how we can get these changes from the remote repository into our repository.

VIDEO

Incase Lam starts making changes to her project that I won't have in my fork of her project, I'll add her project as an additional remote so that I can stay in sync with her.

In my local repository, I already have one remote repository which isoriginremote.

The terminal application showing the existing connect to the remote repository. This is my remote repository and has the shortnameorigin.

Remember that the wordoriginis just the_default_name that's used when yougit clonea remote repository for the first time. We're going to use thegit remotecommand to_add a new_shortname and URL to this list. This will give us a connection to the source repository.

$ git remote add upstream https://github.com/udacity/course-collaboration-travel-plans.git

Notice that I've used the nameupstreamas the shortname to reference the source repository. As with theoriginshortname, the wordupstreamhere is not special in any way; It's just a regular word. This could have been any word... like the word "banana". But the word "upstream" is typically used to refer to the source repository.

Let's check out what the list of remotes looks like now after adding this new remote:

The terminal application show both information about both remotes -originandupstream.

Origin vs Upstream Clarification

One thing that can be a tiny bit confusing right now is the difference between theoriginandupstream. What might be confusing is thatorigindoesnot_refer to the source repository (also known as the"original"_repository) that we forked from. Instead, it's pointing to our forked repository. So even though it has the wordoriginis not actually the original repository.

Remember that the namesoriginandupstreamare just the default or de facto names that are used. If it's clearer for you to name youroriginremotemineand theupstreamremotesource-repo, then by all means, go ahead and rename them. What you name your remote repositories in your local repository does not affect the source repository at all.

Using thegit remote renamecommand to renameorigintomineandupstreamtosource-repo.

⚠️ Resetting Remote Names ⚠️

The image above demos the renaming of the remotes, but I have returned them to their default/defacto names oforiginandupstreamwith the following commands:

$ git remote rename mine origin
$ git remote rename 
source
-repo upstream

Retrieving Upstream Changes

Now to get the changes from upstream remote repository, all we have to do is run agit fetchand use theupstreamshortname rather than theoriginshortname:

$ git fetch upstream master

The terminal application showing the results of doinggit fetch upstream master. A new branch is added to the local repository.

QUESTION 1 OF 2

Now that you've added a connection to the newupstreamremote repository, if you rungit fetch upstream masterwill that update_your forked repository_on GitHub?

• Yes

• No

SUBMIT

Now that we've fetched all of the changes from the upstream remote repository, let's do a log to see what new information we have in our local repository. I'm using the followinggit logcommand to make sure I display_all_commits from_all_branches (including remote and tracking branches!):

$ git 
log
 --oneline --graph --decorate --all

The terminal application showing the log of my local repository after fetching theupstreamremote's changes.

It can be a bit difficult to read with the wrapping of the commit messages but you should be able to see that there is now anupstream/masterremote branch that is ahead of the localmasterbranch.upstream/masteris on commit52e493fwhile themasterbranch is on commit1c12194.

We can use theupstream/masterbranch to keep track of where the source repository's master branch is. We can now get any changes that are made to the source repository'smasterbranch by just runninggit fetch upstream master.

Usinggit fetch upstream masterpulled in the changes from themasterbranch on theupstreamremote repository.

What single command would we use if we want to fetch theupstream/masterchanges_and_merge them into themasterbranch?

SUBMIT: git pull upstream master

Remember from the lesson on remotes that a git pull is the same thing as a git fetch + git merge!

To push these new changes from the Lam's repository, we don't want to rungit push origin upstream/masterbecauseupstream/masteris not a local branch. To get these changes into my forked version of her project, I could mergeupstream/masterinto an existing branch (like the localmasterbranch) and push that.

# to make sure I'm on the correct branch for merging

$ git checkout master


# merge in Lam's changes

$ git merge upstream/master


# send Lam's changes to *my* remote

$ git push origin master

Recap

When working with a project that you've forked. The original project's maintainer will continue adding changes to their project. You'll want to keep your fork of their project in sync with theirs so that you can include any changes they make.

To get commits from a source repository into your forked repository on GitHub you need to:

• get the cloneable URL of the source repository
• create a new remote with the git remote add command
  • use the shortname upstream to point to the source repository
  • provide the URL of the source repository
• fetch the new upstream remote
• merge the upstream 's branch into a local branch
• push the newly updated local branch to your origin repo