github-top-down.md

    Workflows!
        Internals!
Tips & Tricks! 
  Resolving conflicts!
       Reading git output! 

Git - Top down!

Why top-down? Top to use efficiently, down for leaky abstractions.

Roadmap:

• github-flow workflow This workflow is a variation of the git-flow branching model. It assumes a distributed, open-source workflow on Github, and takes advantage of github features, especially forks and pull requests.

• hub-feature by hand After using the hub-feature workflow once, developing a second feature using the traditional porcelain commands shows just how powerful having a workflow layer is, while pointing out where the underlying magic happens.

• conflict scenarios and resolution With multiple developers, things will conflict. Handling conflicts gracefully will keep the project commit log happy, and you sane.

• git internals Seeing how the porcelain works on the underlying git objects clarifies the why behind the common operations. With an understanding of the data structures the index works on, resolving many git issues becomes much more obvious.

• git tips & tricks After the deep dive through the onion of git layers, a few tips and tricks that help throughout the git experience, including a variety of config tweaks to make git come alive.

github-flow

The github-flow workflow takes a similar approach to the git-flow workflow, with two major divergences. Taking advantage of the github fork and pull request features, every developer has a view of the project with three important repositories. The project has one canonical repository, which should be at github.com/organization/project. Each developer has a fork to share code from and submit pull requests against, at github.com/user/project. Each developer also has a local copy of the repository, for day-to-day development.

github-flow is a series of workflow commands which manages moving commits and branches between the three repositories. Data flows in a circular pattern, from the local repository, up to the developer's fork via a branch push, over to the organization via a pull request, and merged changes come back down with a rebase pull.

The second divergence is the heavy use of rebasing in favor of merges. This is two fold- aesthetically, it keeps the master branch "cleaner" and more linear. Each feature is a linear course of development, each merge commit means a feature has been finished. Programmatically, it is easier for github-flow to manage rebases than merges when updating a branch.

• install One time, instructions at github-flow.

• fork/clone Once per fork. Using github-flow configures remotes and configs correctly.

• start Begin work on a new named feature.

• update Pull upstream updates into the project master and the branch.

• review Push changes to a branch on a fork on github, and open a pull request against the upstream project.

• finish Close the pull request, clean up branches.

features by hand

Looking at the github-flow source, every command is a wrapper around one or several git porcelain commands.

• start branch, checkout

• update checkout, rebase, checkout, rebase

• review update, push, open pull request (on the site)

• finish review, close pr, delete branches

Conflict

At some point, there will be a conflict with enough developers touching a finite amount of code. With github-flow, merge conflicts are isolated to occur only in actively developed feature branches. With somewhat continuous feature updates, it is unlikely that branches will get too far diverged from master, and thus unlikely there will be too many merge conflicts. When they do occur, there are a few strategies to handle them.

• rebase Before looking at how to solve merge conflicts, it's important to see how merge conflicts occur.

• merge markers Most important in understanding conflict resolution is how to read git status, git diff, and merge markers. Once the conflicting hunk is found, the developer can edit the file, remove the merge markers, and add the resolved file.

• ours, theirs Often, either our version or their version is correct. In that case, the developer can quickly get all of the edits by running git checkout --<ours|theirs> <filename> and adding the file.

• bailing At some point, a rebase will get so bad it's not worth fixing. At that point, it's better to throw everything away and start over with a different approach. git rebase --abort, then cherry pick.

  • cherry-pick After bailing from a rebase with too many merge conflicts, a good solution is to create a temporary branch off master, cherry-pick the commits from the feature branch, resolve the conflicts, and finally replace the old feature branch with the new temp branch.

• pretty rebase Rebasing can be used within a branch to clean up history.

Internals

• hashes
• objects
• trees
• commits
• commitishes
• packs

Tips & Tricks

• completion Just turn it on, learn to tab, save time remembering trivialities like issue number. Also ps1 commands.

• colorize Like tab-complete, makes it much easier to read output.

• show-branch Using github-flow, this isn't usually an issue, but with three or four concurrent feature branches, this is a great way to see what is where

• plog

  • --since
  • -[n]
  • --author