What is Git Stream and How to Use It?

Umar Farooque Khan
4 min readMay 30, 2024

--

Git is a tool used in software development to keep track of changes in code. One important thing it does is manage something called ‘upstream’ repositories. This guide is here to make ‘git upstream’ easier to understand and show you how it works with some real examples.

What is Git Upstream?

Git Upstream is the connection between your local repository and its remote version. It lets you keep the two in sync by transferring changes. This connection is important when you’re starting a new repository or working on a forked one.

Significance of Upstream Branches

Upstream branches play a pivotal role in facilitating collaboration within a development team. By keeping track of changes made in the upstream repository, developers can ensure that their local copies remain up to date with the latest developments. This synchronization is vital for avoiding conflicts, integrating new features seamlessly, and maintaining code consistency across the project.

Setting Upstream in Git

Now, let’s explore some common scenarios and commands involved in working with upstream branches.

1. Checking Remote Configuration:

To view the remote repositories associated with your local repository, you can use the git remote command:

git remote -v

This command displays the URLs of the remote repositories along with their corresponding names.

2. Adding an Upstream Remote:

If you haven’t already configured an upstream remote, you can add it using the git remote add command:

git remote add upstream <upstream_repository_URL>

This command establishes a connection to the upstream repository, enabling you to fetch changes from it.

3. Fetching Changes from Upstream:

To fetch the latest changes from the upstream repository, use the git fetch command:

git fetch upstream

This command retrieves the latest commits and updates your local repository’s references to the upstream branches.

4. Updating Local Branches:

After fetching changes from the upstream repository, you may want to update your local branches to incorporate these changes. One common approach is to merge the upstream changes into your local branch:

git checkout <your_branch>
git merge upstream/main

Replace <your_branch> with the name of your local branch. This command merges the changes from the upstream main branch into your current branch.

5. Pushing Changes to Upstream:

Once you’ve made changes to your local branch and want to contribute them to the upstream repository, you can push your commits using the git push command:

git push upstream <your_branch>

This command pushes your changes to the specified branch in the upstream repository, enabling other collaborators to review and integrate your work.

Practical Example Scenario:

Imagine you’re a developer interested in contributing to an open-source project hosted on GitHub. The project, let’s call it “AwesomeProject,” is maintained by a team of developers, and you want to add a new feature to it. Here’s how you would utilize upstream branches and forking:

Forking the Repository:

You start by forking the “AwesomeProject” repository on GitHub. This creates a copy of the repository under your GitHub account, allowing you to work on it independently.

Cloning Your Fork:

Next, you clone your forked repository to your local machine using the git clone command:

git clone https://github.com/yourusername/AwesomeProject.git

Configuring Upstream:

To keep track of changes made to the original “AwesomeProject” repository, you add it as an upstream remote:

git remote add upstream https://github.com/originaluser/AwesomeProject.git

Creating a Feature Branch:

Before making any changes, you create a new branch to work on your feature:

git checkout -b feature-branch

Implementing the Feature:

You make the necessary changes to add the new feature, committing your work as you progress:

git add . git commit -m "Implemented new feature"

Fetching and Syncing with Upstream:

Periodically, you fetch changes from the upstream repository to ensure your local copy is up to date:

git fetch upstream git merge upstream/main

Resolving Conflicts (if any):

If there are any conflicts between your changes and the upstream changes, you resolve them locally by editing the conflicting files and committing the changes.

Pushing Changes to Your Fork:

Once you’re satisfied with your changes and have resolved any conflicts, you push your feature branch to your forked repository on GitHub:

git push origin feature-branch

Creating a Pull Request:

Finally, you navigate to your forked repository on GitHub and create a pull request (PR) to merge your feature branch into the original “AwesomeProject” repository. In the PR description, you explain the changes you’ve made and why they should be merged.

Review and Merge:

The maintainers of “AwesomeProject” review your pull request, providing feedback and suggesting any necessary changes. Once approved, your changes are merged into the main branch of the original repository.

Conclusion:

By following this workflow, you effectively utilize upstream branches in conjunction with forking to contribute to open-source projects on platforms like GitHub. This approach allows for independent development while ensuring synchronization with the original repository and facilitating collaboration with the project maintainers.

--

--

Umar Farooque Khan
Umar Farooque Khan

Written by Umar Farooque Khan

Experienced software developer with a passion for clean code and problem-solving. Full-stack expertise in web development. Lifelong learner and team player.