Git basics are very simple, but it sometimes feels like a bottomless pit when you find yourself on the wrong side of a confusing error situation. It’s doubly frustrating because you think that messing up or trying the wrong solution can lose data. It’s actually very hard to “lose” data with Git but it can certainly be hiding somewhere you wouldn’t think to look without an experienced dev poking around.
The thing about Git is that, unless you’ve got a seriously impressive memory, you can’t just learn it by reading about it up front… you need to do it. Find a problem you want to go back and fix, hit an error in your merge, etc. and Google the hell out of it, learning a new Git tactic in the process.
To help you out, come back and refer to this lesson again when you’re in trouble. We’ll first cover a real-world example of a GitHub workflow used on this very project. The Additional Resources section below should also help you find high quality resources for when you need them later on.
This section contains a general overview of topics that you will learn in this lesson.
Let’s say you want to contribute to the web application that powers this website (it’s a different repo than our curriculum content, this is our site repo).
How do you contribute when you do not have write access to the repository? Below is a production-ready workflow that is actually used by contributors to this website. We’ll assume here that you have commented on an open issue on our repo and that it has been assigned to you.
The key players in this story will be the
upstream (the original GitHub repository), the
origin (your fork of that repo), and the “local” repository (your local clone of
origin). Think of it as a happy triangle… except that “local” can only pull from
upstream, not push.
git clone email@example.com:your_user_name_here/theodinproject.git(you can get the url from the little widget on the sidebar on the right of that repo’s page on GitHub).
origin, which is your fork on GitHub. You will use this to push changes back up to GitHub. You’ll also want to be able to pull directly from the original repository on GitHub, which we’ll call
upstream, by setting it up as another remote. Do this by using
git remote add upstream firstname.lastname@example.org:TheOdinProject/theodinproject.gitinside the project folder
We’ve got one main branch –
main is for production-ready code. Any code deployed to
main (on the original repo, not on your fork) will be tested in staging and shipped to production. You’ll be working in a feature branch and submitting your pull requests to the
mainbranch is probably out of date. Fetch the most updated copy using
git fetch upstream.
git merge. Specifically, you’ll first want to make sure you’re on your
git checkout mainand then
git merge upstream/mainto merge in those upstream changes that we just fetched.
git fetch upstreamfollowed by a
git merge upstream/some_branchis the EXACT same thing as doing a
git pull upstream/some_branch. We prefer to split it up here so that we can explicitly walk through the steps.
mainbranch is up-to-date with upstream, you need to merge it into your feature branch. Yes, that is correct and it seems odd at first. Don’t you want to merge the feature branch into the
mainbranch instead? Yes, you do, but not yet. Your feature branch is dirty. You don’t know if it has any conflicts which might creep up. Any time you are merging in more “senior” branches (e.g. merging the feature into
main), you want it to be a clean and conflict-free merge if possible. So you first merge the “senior” branch into your dirty branch to resolve those conflicts. Run
git checkout your_feature_nameto jump back onto your feature branch, then
git merge mainto merge
main, the hard part is all over. All that’s left is to make the Pull Request (often abbreviated as PR) against our
upstreamrepo on GitHub!
origin(your fork of the
upstreamrepository). You can’t send directly to
upstreambecause you don’t have access, so you’ll need to make a pull request. Use
git push origin your_feature_nameto ship your feature branch up to your fork on GitHub.
mainbranch. This can be done using GitHub’s interface.
This section contains questions for you to check your understanding of this lesson. If you’re having trouble answering the questions below on your own, review the material above to find the answer.
This section contains helpful links to other content. It isn’t required, so consider it supplemental..
Sometimes (okay, maybe a lot of times) when you’re working with Git, something goes terribly wrong. Don’t panic! Git is designed to help you recover from your misfortune. These resources will help you get back on track towards version control nirvana: