Trees and branches. Is this some sort of analogy? Photo by . Liam Pozz → Understanding Git (part 3) — Resolving Conflicts (stay tuned!) Understanding Git (part 1) — Explain it Like I’m Five Understanding Git (part 2) — Contributing to a Team Practically every major software company and project uses some type of “version control” to track changes over time. Version control can help you coordinate teamwork and hunt down software bugs. open-source is one of the most popular version control systems today. See of this series for an “Explain it Like I’m Five” intro if you’re not already familiar. Git part 1 This guide covers how to use 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. git Any will be highlighted in bold the first time it’s described. Feel free to look up those terms in the official or for more details. jargon git glossary reference guide 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 of a tree 🎄 trunk Every time you add more changes (aka ), 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. commits Git, by default, calls the trunk . You can call it whatever you want; there’s nothing special about the word other than that it’s conventional. master master You can travel up and down the trunk — equivalent to going forward and backward in time — by specific “checkpoints” as described in . checking out part 1 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 ( ). 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. master The solution is branching. Instead of committing to the trunk, you create your own personal (e.g. instead of ) and work from there. Now you’re growing your taller instead of the trunk. branch my-cool-feature master branch 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: 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 . While you were working on your branch (commits and ), someone else worked directly on the trunk (commits and ). Those commits aren’t in your branch yet; your branch is out of date, which you’ll read about soon. T2 B1 B2 T3 T4 Again, see of this series to understand the and commands, or see the free if you want more visualizations. You can also see real life branch visualizations on , or by typing in your terminal. part 1 branch commit git book GitHub git log --all --decorate --oneline --graph 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 (PR) or a (MR) — they’re the same thing, the term just depends on what software you’re using (e.g. GitHub/Bitbucket/GitLab). You’re that your changes be . I’ll refer to these as PRs from here on. pull request merge request requesting pulled in and merged 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 ecosystem. open-source Here’s a of exactly how to submit a PR, and some about PR etiquette. There’s even a whole community of “ ” for people who want to start contributing to open-source but don’t know where to begin. detailed description advice First Timers Only The main thing to remember is to include a clear explanation of you’re making the changes in order to give context. why 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 again. The PR will update automatically to reflect your changes. origin 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: You can “ ” the changes using . This will apply any new changes from the trunk on top of your work. in merge git merge master You can “ ” the changes using . This re-applies your work on top of any new changes on the trunk. on top of rebase git rebase master 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 if you’re unsure. merge Dealing with conflicts When merging or rebasing, you’ll occasionally run into . This means you changed a line of code that someone else also changed, and git doesn’t know which version to keep. conflicts 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 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. this article 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” the “!”, which had each been added separately. and 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 below is a “merge commit”, putting the changes from your green branch onto the trunk. T5 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 If you found this guide useful, please help by so others can find it too. tapping the 👏 button as many times as you’d like Thanks for reading, and stay tuned for part 3. In the meantime, go watch this video and then tackle some issues! easy tutorial First Timers
