Back to list
Forking projects to make your own changes lets you easily integrate your own contributions. But if you're not sending those changes back upstream—which means sending it back to the parent repository—you're at risk for losing track of them, which can cause divergent lines in your repository. To make sure all contributors are drawing from the same place, you'll need to know some principles of how git forking interacts with git upstream. In this blog, I'll introduce you to the basics, the gotchas, and even leave you with a cool tip to get you ahead of the curve.
Git upstream: Keep up-to-date and contribute
Let me start by detailing a common setup and the most basic workflow to interact with upstream repositories.
In a standard setup, you generally have an origin and an upstreamremote — the latter being the gatekeeper of the project or the source of truth to which you wish to contribute.
First, verify that you have already setup a remote for the upstream repository, and hopefully an origin too:
If you don't have an upstream you can easily add it with the remote command:
KISS is an acronym for Keep It Simple Stupid, which is a design principle noted by the U.S. Navy in 1960s.The KISS principle states that most systems work best if they are kept simple rather than made complicated; therefore, simplicity should be a key goal in design, and unnecessary complexity should be. Whether you are working with open-source or private repositories, you will want to learn the Git fork and pull request workflow. The biggest difference between a Git fork and pull request workflow and a Git branch workflow is that in forking you are working on your own copy of the project and not within the project. You push changes to your fork without changing the original project and then. Starting in May 2014, it is possible to update a fork directly from GitHub. This still works as of September 2017, BUT it will lead to a dirty commit history. Open your fork on GitHub. Click on Pull Requests. Click on New Pull Request. By default, GitHub will compare the original with your fork, and there shouldn't be anything to compare if you.
Verify that the remote is added correctly:
Quicken willmaker plus 2019 v19 5 2429. Now you can collect the latest changes of the upstream repository with fetch. Repeat this every time you want to get updates:
(If the project has tags that have not merged to master you should also do: git fetch upstream --tags)
Generally, you want to keep your local master branch as a close mirror of the upstreammaster and execute any work in feature branches, as they might later become pull requests.
At this point, it does not matter if you use merge or rebase, as the result will typically be the same. Let's use merge:
When you want to share some work with the upstream maintainers you branch off master, create a feature branch. When you're satisfied, push it to your remote repository.
You can also use rebase instead, then merge to make sure the upstream has a clean set of commits (ideally one) to evaluate:
If you need to squash a few commits into one you can use the awesome rebase interactive at this point.
Publish with git fork
After the above steps, publish your work in your remote fork with a simple push:
A slight problem arises if you have to update your remote branch feature-x after you've published it, because of some feedback from the upstream maintainers. You have a few options:
- Create a new branch altogether with the updates from you and the
upstream. mergethe updates fromupstreamin your local branch which will record a merge commit. This will clutter theupstreamrepository.Rebaseyour local branch on top of the updates fromupstreamand do aforcepush onto your remote branch:
Personally I prefer to keep the history as clean as possible and go for option three, but different teams have different workflows. Note: You should do this only when working with your own fork. Rewriting history of shared repositories and branches is something you should NEVER do.
Tip of the day: Ahead/Behind numbers in the prompt
After a fetch, git status shows you how many commits you are ahead or behind of the synced remote branch. Wouldn't it be nice if you could see this information at your faithful command prompt? I thought so too so I started tapping with my bash chopsticks and cooked it up.
Here is how it will look on your prompt once you've configured it:
System monitor 2 7. And this is what you'll need to add to your .bashrc or equivalent—just a single function:
You can enrich your bash prompt with this new function, ahead_behind, to have the desired effect. I leave the colorization as an exercise for the reader.
Sample prompt:
Inner workings
For those who like details and explanations here is how it works:
We get the symbolic name for the current HEAD, i.e. the current branch:
We get the remote that the current branch is pointing to: Ad free tidal music converter 1 4 00.
We get the branch onto which this remote should be merged (with a cheap Unix trick to discard everything up to and including the last forward slash [ / ]):
Now we have what we need to collect the number of counts for the commits we are ahead or behind:
We use the age-old Unix tr to convert the TAB to a separator |.
Getting started with git upstream
That is a basic walk-through on git upstream — how to set up a git upstream, create a new branch, collect changes, publish with git fork, and a sweet tip for how many commits ahead/behind you are of your remote branch.
Bitbucket Server includes fork synchronization which basically relieves the developer from all the burden of keeping up to date with its forks, and Bitbucket Cloud has an easy 1-step sync check it out!
Follow me @durdn and the awesome @Bitbucket team for more DVCS rocking.
After using GitHub by yourself for a while, you may find yourself wanting to contribute to someone else's project. Or maybe you'd like to use someone's project as the starting point for your own. This process is known as forking.
Creating a 'fork' is producing a personal copy of someone else's project. Forks act as a sort of bridge between the original repository and your personal copy. You can submit Pull Requests to help make other people's projects better by offering your changes up to the original project. Forking is at the core of social coding at GitHub.
For this tutorial, we'll be using the Spoon-Knife project, a test repository that's hosted on GitHub.com that lets you test the Pull Request workflow.
Fork the repository
To fork the Spoon-Knife repository, click the Fork button in the header of the repository.
Sit back and watch the forking magic. When it's finished, you'll be taken to your copy of the Spoon-Knife repository.
Clone your fork
You've successfully forked the Spoon-Knife repository, but so far, it only exists on GitHub. To be able to work on the project, you will need to clone it to your computer.
If you're using GitHub Desktop, this process is a breeze. On your fork of Spoon-Knife, navigate over to the right hand side bar and click Clone or Download. How you clone is up to you. Some options are cloning with the command line, or by using GitHub Desktop.
Making and pushing changes
Git Fork Gui
Go ahead and make a few changes to the project using your favorite text editor, like Atom. You could, for example, change the text in index.html to add your GitHub username.
When you're ready to submit your changes, stage and commit your changes.
Is staging and committing changes locally too advanced right now? Check out this on-demand training for interactive tutorials to help you learn more.
Git Fork Free
Right now, you've essentially told Git, 'Okay, I've taken a snapshot of my changes!' You can continue to make more changes, and take more commit snapshots. When you're ready to push your changes up to GitHub.com, push your changes to the remote.
Making a Pull Request
At last, you're ready to propose changes into the main project! This is the final step in producing a fork of someone else's project, and arguably the most important. If you've made a change that you feel would benefit the community as a whole, you should definitely consider contributing back.
To do so, head on over to the repository on GitHub.com where your project lives. For this example, it would be at https://www.github.com//Spoon-Knife. You'll see a banner indicating that you've recently pushed a new branch, and that you can submit this branch 'upstream,' to the original repository:
Clicking on Compare and Pull Request sends you to a discussion page, where you can enter a title and optional description. It's important to provide as much useful information and a rationale for why you're making this Pull Request in the first place. The project owner needs to be able to determine whether your change is as useful to everyone as you think it is.
When you're ready typing out your heartfelt argument, click on Send pull request. You're done!
Pull Requests are an area for discussion. In this case, the Octocat is very busy, and probably won't merge your changes. For other projects, don't be offended if the project owner rejects your Pull Request, or asks for more information on why it's been made. It may even be that the project owner chooses not to merge your pull request, and that's totally okay. Your copy will exist in infamy on the Internet. And who knows–maybe someone you've never met will find your changes much more valuable than the original project. Share and share alike!
Huzzah!
You've successfully forked and contributed back to a repository. Go forth, andcontribute some more!
Last updated Nov 30, 2017
