![](https://hackernoon.com/hn-images/1*bSzuCHAmXrtoEhBk3zq5PQ.jpeg)

Trees and branches. Is this some sort of analogy? Photo by [Liam Pozz](https://unsplash.com/photos/4iwLxkESGe4?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText).

> [Understanding Git (part 1) — Explain it Like I’m Five](https://hackernoon.com/understanding-git-fcffd87c15a3)  
> → [Understanding Git (part 2) — Contributing to a Team](https://hackernoon.com/understanding-git-2-81feb12b8b26)  
> Understanding Git (part 3) — Resolving Conflicts (stay tuned!)

Practically every major software company and [open-source](https://hackernoon.com/tagged/open-source) project uses some type of “version control” to track changes over time. Version control can help you coordinate teamwork and hunt down software bugs.

[Git](https://git-scm.com/downloads) is one of the most popular version control systems today. See [part 1](https://hackernoon.com/understanding-git-fcffd87c15a3) of this series for an “Explain it Like I’m Five” intro if you’re not already familiar.

This guide covers how to use [git](https://hackernoon.com/tagged/git) to contribute to a team — whether at an office or online in the open-source community — and is intended for beginners. It’ll explain the whole flow, from idea to Pull Request.

Any **jargon** will be highlighted in bold the first time it’s described. Feel free to look up those terms in the official [git glossary](https://git-scm.com/docs/gitglossary) or [reference guide](https://git-scm.com/docs) for more details.

### Starting from the trunk

Git uses a lot of “tree” analogies, so get ready for it. You can think of your main codebase as the **trunk** of a tree 🎄

Every time you add more changes (aka **commits**), your tree grows taller, straight up. Even if you delete code, that’s still considered a change and causes the tree to grow. It’s like how the “undo” history in a text editor saves your keystrokes, including backspace.

Git, by default, calls the trunk `master`. You can call it whatever you want; there’s nothing special about the word `master` other than that it’s conventional.

You can travel up and down the trunk — equivalent to going forward and backward in time — by **checking out** specific “checkpoints” as described in [part 1](https://hackernoon.com/understanding-git-fcffd87c15a3).

### Branching out

Most projects have a backlog of new features to add and bugs to fix. When you want to address one of these issues, one way would be to grow the tree taller and commit directly to the trunk (`master`). This works fine for small projects or projects where you’re the only person making changes, but what if multiple people are working at the same time? It’s too easy to get in each other’s way and end up with conflicting changes.

The solution is branching. Instead of committing to the trunk, you create your own personal **branch** (e.g. `my-cool-feature` instead of `master`) and work from there. Now you’re growing your _branch_ taller instead of the trunk.

When visualizing branches, they’re often drawn sideways to save space. Imagine the following is an ugly tree, tipped over, with the roots on the left. Each circle is a commit. The farther to the right each circle is, the more recently it was committed:

![](https://hackernoon.com/hn-images/1*qsdaWGlvPQ58GcMWxDRzCQ.png)

I wouldn’t plant this in my front yard.

There’s a blue trunk and a green branch. There are several commits on each, shown chronologically from left to right. Your branch started at commit `T2`. While you were working on your branch (commits `B1` and `B2`), someone else worked directly on the trunk (commits `T3` and `T4`). Those commits aren’t in your branch yet; your branch is out of date, which you’ll read about soon.

Again, see [part 1](https://hackernoon.com/understanding-git-fcffd87c15a3) of this series to understand the `branch` and `commit` commands, or see the free [git book](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging) if you want more visualizations. You can also see real life branch visualizations on [GitHub](https://github.com/cooperka/react-native-snackbar/network), or by typing `git log --all --decorate --oneline --graph` in your terminal.

### Submitting your changes

Now you have your changes on a branch, but the eventual goal is to get them back onto the trunk as part of the “official” codebase.

Once you’ve tested your changes, you’ll need to share them with the team. Typically you’ll do this via a **pull request** (PR) or a **merge request** (MR) — they’re the same thing, the term just depends on what software you’re using (e.g. GitHub/Bitbucket/GitLab). You’re _requesting_ that your changes be _pulled in and merged_. I’ll refer to these as PRs from here on.

Some people get nervous about making their first PR (I certainly did), but it’s really nothing to be afraid of. Most teams are happy to receive new PRs, even if the code needs a bit of work before being accepted. PRs are an important part of the [open-source](https://opensource.guide/) ecosystem.

Here’s a [detailed description](https://yangsu.github.io/pull-request-tutorial/) of exactly how to submit a PR, and some [advice](https://readwrite.com/2014/07/02/github-pull-request-etiquette/) about PR etiquette. There’s even a whole community of “[First Timers Only](http://www.firsttimersonly.com/)” for people who want to start contributing to open-source but don’t know where to begin.

The main thing to remember is to include a clear explanation of **why** you’re making the changes in order to give context.

### Discussing and revising

Once you submit your PR, someone else on the team will need to look it over and leave feedback. They can ask questions and comment on specific lines of code, or they can give more general feedback about your changes. In some cases they may push their own changes directly to your branch, but usually they’ll ask you to make the changes yourself.

If you want to make changes based on the feedback, simply add more commits to your existing branch and push it to `origin` again. The PR will update automatically to reflect your changes.

### Keeping up to date

If some time goes by before your PR is accepted, it might get “stale”, meaning it’s based on an older version of the trunk (like in the tree shown earlier). Your changes may have worked a week ago, but there’s no guarantee that they still work alongside other, more recent changes to the trunk.

To get up to date, you have two options:

1.  You can “[**merge** in](https://git-scm.com/book/en/v2/Git-Branching-Rebasing)” the changes using `git merge master`. This will apply any new changes from the trunk on top of your work.
2.  You can “[**rebase** on top of](https://git-scm.com/book/en/v2/Git-Branching-Rebasing)” the changes using `git rebase master`. This re-applies your work on top of any new changes on the trunk.

In either case, your own changes will still be the same — you’re effectively just moving your branch up to the top of the trunk to stay up to date with the latest code.

Different teams may prefer one method or the other; it’s usually safer to `merge` if you’re unsure.

### Dealing with conflicts

When merging or rebasing, you’ll occasionally run into **conflicts**. This means you changed a line of code that someone else also changed, and git doesn’t know which version to keep.

When this happens, many people panic. The output from git looks really nasty, with weird `>>>>>>> ======= <<<<<<<` symbols, and you might think you’ve broken the whole thing. Don’t worry! It looks strange, but with a bit of practice you’ll understand it.

There’s way too much to cover here, but check out [this article](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging#_basic_merge_conflicts) to understand how conflicts work and how to resolve them. I also plan to focus on dealing with conflicts in part 3 of this series.

In essence, you just need to remove those weird symbols and manually combine the code in between them.

For example, the line:

print "Hello"

Might be changed on two separate branches, leading to the conflict:

\>>>>>>>  
print "Hello, world"  
\=======  
print "Hello!"  
<<<<<<<

Which, when resolved, might become:

print "Hello, world!"

After manually merging the conflicting lines together — keeping both the “world” _and_ the “!”, which had each been added separately.

### Accepting your changes

Once all of the PR comments have been addressed and any conflicts have been resolved, your branch is ready to be merged!

An administrator of the codebase can accept the PR by merging your branch into the trunk — simply by pressing a button on GitHub — thus making your changes official.

Commit `T5` below is a “merge commit”, putting the changes from your green branch onto the trunk.

![](https://hackernoon.com/hn-images/1*0zlMKn2cVGIPl1ZT4G8ngg.png)

This isn’t how trees work in nature.

You’ve made a successful contribution! 🙌 You can view all the PRs you’ve ever submitted at [https://github.com/pulls](https://github.com/pulls).

If you found this guide useful, please help by **tapping the 👏 button as many times as you’d like** so others can find it too.

Thanks for reading, and stay tuned for part 3. In the meantime, go watch this [easy tutorial](https://www.youtube.com/watch?v=V74l_zS1x8E) video and then tackle some [First Timers](http://www.firsttimersonly.com/) issues!

Flow

Alongside

ReadWrite

YouTube

Read My Stories

Too Long; Didn't Read

Cassandra Forward a free Cassandra-focused community event

Understanding Git (part 2) — Contributing to a Team

Too Long; Didn't Read

Companies Mentioned

Coin Mentioned

@cooperka

RELATED STORIES