Understanding origin and upstream

When you start interacting with remote repositories using commands like git clone, git fetch, git pull, and git push, you'll frequently encounter the names origin and sometimes upstream. These are not special Git keywords but rather widely adopted conventions for naming remote repositories. Understanding what they typically represent makes collaborative workflows much clearer.

The Default Remote: origin

Think back to the git clone command. When you clone a repository from a hosting platform like GitHub or GitLab using a command like:

git clone https://github.com/someuser/someproject.git

Git does two main things:

1. It copies all the project data (commits, branches, etc.) to your local machine, creating a new directory named someproject.
2. It automatically configures a remote connection pointing back to the URL you cloned from. By default, Git names this remote connection origin.

So, origin is simply the default shorthand name Git assigns to the remote repository you cloned from. It's a convention that shows "where this local repository came from." You can verify this immediately after cloning by running git remote -v:

cd someproject
git remote -v
# Output will likely show:
# origin  https://github.com/someuser/someproject.git (fetch)
# origin  https://github.com/someuser/someproject.git (push)

This shows that the name origin is associated with the original URL for both fetching (downloading) and pushing (uploading) operations. Because it's the default, many Git commands that interact with remotes (like git fetch, git pull, git push) will use origin if you don't explicitly specify another remote name. For example, git push is often equivalent to git push origin.

While origin is the default, it's important to remember it's just a name. You could remove it or rename it using git remote rename origin destination, although deviating from this convention is uncommon unless you have a specific reason.

The Source Project: upstream

The convention of using upstream usually comes into play in collaborative scenarios, particularly in open source development or when working with forks. A common workflow involves:

1. Forking: You find a project on a platform like GitHub (let's call it the "original" project) that you want to contribute to or experiment with. You create your own copy of this repository on the platform. This copy is called a "fork."
2. Cloning: You then clone your fork (not the original project directly) to your local machine. As we just learned, Git automatically sets up a remote named origin pointing to your fork on GitHub.
3. Contributing/Updating: You make changes locally, push them to your origin (your fork). To contribute back to the original project, you'd typically create a Pull Request from your fork. Crucially, the original project might receive updates from other contributors while you're working. You'll want to pull these updates into your local repository and your fork to keep them synchronized.

This is where upstream comes in. To keep track of the original project repository (the one you initially forked), it's conventional to add another remote connection and name it upstream. You would do this manually using git remote add:

# Inside your locally cloned fork's directory
git remote add upstream https://github.com/original-owner/original-project.git

# Verify the remotes
git remote -v
# Output will now show both origin and upstream:
# origin    https://github.com/your-username/original-project.git (fetch)
# origin    https://github.com/your-username/original-project.git (push)
# upstream  https://github.com/original-owner/original-project.git (fetch)
# upstream  https://github.com/original-owner/original-project.git (push)

Now you have two named remotes:

• origin: Points to your personal fork on the hosting platform. You typically have push access here.
• upstream: Points to the original project repository that you forked from. You typically only have fetch access here (unless you are a direct collaborator on the original project).

You can then use upstream to fetch changes from the original project and merge them into your local work:

# Fetch branches and commits from the original project
git fetch upstream

# Switch to your local main branch (or equivalent)
git switch main

# Merge changes from the upstream main branch into your local main branch
git merge upstream/main

# Push the updated main branch (including upstream changes) to your fork
git push origin main

Relationship between Local, Origin (Fork), and Upstream (Original Project) repositories. Solid lines represent direct Git operations, dashed lines represent actions often performed via the hosting platform interface.

In summary:

• origin is the default name for the remote you cloned from, typically your fork or your primary remote copy.
• upstream is the conventional name for the original remote repository that you forked from, used primarily to fetch updates.

While you can name your remotes anything you like, adhering to the origin and upstream conventions makes your workflow instantly understandable to other developers familiar with Git and collaborative development practices. These names provide context about the intended purpose of each remote connection.