Introduction
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.
Lesson Overview
This section contains a general overview of topics that you will learn in this lesson.
- Using Git to make open source contributions
A Git Workflow For Open Source Contribution
Let’s say you want to contribute to the repo that houses our curriculum content
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.
Initial Setup
- Read the contributing guide for the project.
- Fork the original (“upstream”) repository into your own GitHub account by using the “fork” button at the top of that repo’s page on GitHub.
- Clone your forked repository onto your local machine using something like
git clone git@github.com:your_user_name_here/curriculum.git
(you can get the url from the little widget on the sidebar on the right of that repo’s page on GitHub). - Because you cloned the repository, you’ve already got a remote that points to
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 callupstream
, by setting it up as another remote. Do this by usinggit remote add upstream git@github.com:TheOdinProject/curriculum.git
inside the project foldercurriculum
.
Ongoing Workflow
We’ve got one main branch – main
. 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 main
branch.
- Create a new feature branch for whatever feature you want to build, and add commits following the same practices that you learned about in the branching section of our Revisiting Rock Paper Scissors lesson.
- When you’re done with your feature, odds are that someone has made changes to the upstream repository in the meantime. That means that your
main
branch is probably out of date. Fetch the most updated copy usinggit fetch upstream
. - Now merge the upstream’s changes into your local version of
main
usinggit merge
. Specifically, you’ll first want to make sure you’re on yourmain
branch usinggit checkout main
and thengit merge upstream/main
to merge in those upstream changes that we just fetched. - Note that a
git fetch upstream
followed by agit merge upstream/some_branch
is the EXACT same thing as doing agit pull upstream some_branch
. We prefer to split it up here so that we can explicitly walk through the steps. - Now that your
main
branch 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 themain
branch 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 intomain
), 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. Rungit checkout your_feature_name
to jump back onto your feature branch, thengit merge main
to mergemain
into it. - You may have merge conflicts… resolve those using the skills you learned in the Deeper Look at Git lesson! (JS Course Link)
Sending Your Pull Request
- Now that your feature branch is squeaky clean and you know it’ll merge cleanly into
main
, the hard part is all over. All that’s left is to make the Pull Request (often abbreviated as PR) against ourupstream
repo on GitHub! - Now you want to send your feature branch back up to your
origin
(your fork of theupstream
repository). You can’t send directly toupstream
because you don’t have access, so you’ll need to make a pull request. Usegit push origin your_feature_name
to ship your feature branch up to your fork on GitHub. - If you have been following along with the above steps to get familiar with this workflow, you should stop at this point. If you have completed an assigned issue, the final step is to submit a pull request to merge your feature branch into the original
upstream
repository’smain
branch. This can be done using GitHub’s interface. - Shake your moneymaker, you’re an OSS contributor!
Knowledge Check
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.
Additional Resources
This section contains helpful links to other content. It isn’t required, so consider it supplemental.
- Seth Robertson’s Git Best Practices
- Git Branching and Tagging Best Practices on SO
- Git Best Practices Workflow Guidelines
- GitHub’s official training site
- Understand Git Conceptually
- Learn about Git Branching from Peter Cottle using his interactive branching tutorial.
- Need more still? See this meta-list of git tutorials for beginners.
- Git Immersion is another great tutorial to learn the shortcuts of git (if you’re following the Ruby path or are willing to learn some Ruby).
- Contributing to Open Source is a tutorial video reviewing this lesson.
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:
- Oh sh!t git is a quick reference to get you out of common Git problems.
- This article on How to undo (almost) anything with Git will walk you through some of many options Git provides for undoing various mistakes.
- If the problem you’re facing is more advanced, you can click through this more in-depth guide to find the answer to your specific question.