computer science, research

The Basics of Git Flow

The following is an introduction to the basics of Git and Git Flow:

What are Git and Git Flow?

  • Git is a version control system for tracking changes in files
    • Sort of like Dropbox, people can make changes to files and folders and their teammates can stay up to date with those changes
    • Can be controlled via the command line, your IDE, an external tool, and probably multiple other ways I’m not familiar with
      • I recommend an external tool, I use SourceTree and reference it a few times within this document.
  • Git Flow is a standard set of guidelines for using Git
    • Makes it easier to coordinate work and avoid accidental loss of files/changes
    • Takes some getting used to, but ultimately makes your life easier

potcguidelines

The key word in the definition of Git Flow is guidelines, but while they are not strictly enforced rules, they are the most widely accepted way of organizing Git within the industry.

Terminology

  • repository – where all the code is stored (kinda like a folder in Dropbox)
  • branch – where a specific version of the code is (like a folder within the Dropbox folder)
  • commit – small change in code saved on a branch
  • local – code/branches/commits saved on your computer
  • remote – code/branches/commits not saved on your computer
  • head – the commit you are working on currently
  • checkout – switches the current branch
  • clone – making a local copy of the repo, with the ability to add to/change it
  • merge – combining the code of 2 branches together
  • fetch – gets remote commits of a branch (doesn’t merge)
  • pull – fetches and merges commits from other branches
  • push – adds your local commits to the remote branch for others to pull

Simplified Workflow

Here is a simplified workflow of branching, committing, etc. This is similar to the visual tree view you would see within Source Tree. A solid dot represents a commit. A commit with a white dot on it represents the head, or current commit. A line between two commits shows their connection, either on the same branch, one is branched off of the other, or one is merged into the other (I think it’ll make sense once you look at it).

Screen Shot 2017-10-17 at 12.56.10 PM

Branches and Commits Conventions

When you create a branch you must give it a name and when you commit code you must include a commit message, here are some guidelines on naming branches and writing commit messages:

  • Branches should only accomplish one thing and be named as such
    • Not your name or something encompassing multiple features
      • (Unless maybe it is a sub branch to work of off for that piece, though I’d suggest a directory instead e.g. post-comment branched off of backend vs backend/post-comment)
    • Bad Branch Names: rachels-branch, backend
    • Good Branch Names: login-screen-ui, get-userid
  • Commits should only do one thing and messages should be in the present tense beginning with a verb
      • ‘add sort function’ NOT ‘added sort function and…’

Stash, Reset, & Revert

Mistakes happen, but these are three ways to help fix them! I have a hard time describing these, so I’ve taken definitions from some of Atlassian’s Git Tutorials and linked to each of them

  • Stash
    • “temporarily shelves (or stashes) changes you’ve made to your working copy so you can work on something else, and then come back and apply them later on”
    • More details
  • Reset
    • “a simple way to undo changes that haven’t been shared with anyone else”
    • More details
  • Revert
    • “undoes a commit by creating a new commit”
    • More details

Merging

Merging branches happens when you finish a feature on that branch and want to combine it with your teammates’ code on another branch. Here’s a little step-by-step on how to merge:

Screen Shot 2017-10-17 at 10.36.11 AM.png

  1. Commit changes, fetch parent branch (Develop in this example), and merge it into child branch (the 2nd Feature branch)
  2. Fix any conflicts and ensure everything is still working as intended
  3. Merge child branch into parent branch
  4. (Optional) If you’re done with the feature, “prune the branch” but do not Force Delete

Merge Conflicts

This is often the scariest part of using git. Everything’s fine, you’re getting work done, when suddenly you get a merge conflict and you have to stop everything to try and fix it. It seems so complicated! What causes this? More importantly, how do you fix it?

First off, “a merge conflict happens when two branches both modify the same region of a file and are subsequently merged. Git can’t know which of the changes to keep, and thus needs human intervention to resolve the conflict” – Stack Overflow answer from user Caleb

So a scenario in which this would occur would be if you and a co worker are working on separate features within in the same file. Your co worker writes a function on line 86 and commits it on his branch. You also add a different function on line 86. When it’s time to merge, conflicts happen because you both added different code on the same line!

So how do you fix merge conflicts? Well, there are a couple different ways,

  1. You can directly edit the affected code. This is what I suggest in most cases. Even with conflicts, all of the code is still within the files. When a conflict happens it gets marked with a bunch of ‘’s, “HEAD”, and a long string of random characters this is just to show you and git that there is a problem here:Screen Shot 2017-10-17 at 1.20.27 PM.png
  2. In Source Tree, you can right click the conflicting files and choose to “Resolve Using Mine” or “Resolve Using Theirs.” This will keep only one version of the conflicting code. “Mine” is the version of the current branch, which you are trying to merge something into. “Theirs” is the version of the branch you are trying to merge into the current branch. I would suggest this method only when you know one version is outdated or it is impossible to merge any other way (for example, Xcode Storyboard files cannot really be merged together) Screen Shot 2017-10-05 at 10.21.59 AM.png
  3. As you see above, when you right click a conflicting file in Source Tree, you can also choose to “Launch External Merge Tool.” This is built into Source Tree, but there are many other tools like it available, including ones which can be launched from the command line. The tools usually have two sides showing the different versions of the code and where the conflicts are. From there, you can choose to include the mine or theirs or both when committing the merge. Here’s what the Source Tree tool looks like on a test project:Screen Shot 2017-10-05 at 10.22.25 AM.png

Now you’re a Git expert!

2b4gjtf

(I mean, besides the fact that we haven’t even talked about forking, detached heads, pull requests, squashing, etc….)

Sources (besides experience):

Git Explained: For Beginners

Git Flow Explained: Quick and Simple

Understanding Git Conflict Markers

Additional Resources:

Atlassian’s Learn Git Tutorial

Git Commands GitHub Cheat Sheet

 

Advertisements
crafts, tutorial

Secret Belgian – Bullet Journal Bookbinding Tutorial

I really like bookbinding, and one of my favorite techniques is Secret Belgian. I’ve taught friends and classmates and even led a workshop on how to make these. For my workshop, I made exhaustive notes, and since bullet journalling is so popular, I thought it’d be nice to share these, since the style of the notes themselves are practically a bullet journaling entry and other people who’ve seen them in real life have found them helpful. And also, how cool and hipster would it be to bullet journal in a book you made? Pretty fuckin’ cool if I do say so myself.

Here are some examples of a finished Secret Belgian journal:

IMG_3880.JPG FullSizeRender 4.jpg

The process of making this book has two basic parts, building the cover and sewing in the pages, so that’s how I split up my notes! Here we go!

Cover1.png

Cover2.png

Inside1.png

Inside2.png

I hope you found this helpful! If you have any questions at all, ask away!

And if you’d like to see more of my work in book binding and print making, here’s a link to my portfolio!