Agenda

• The Good; The Bad; The Ugly
• Repository architecture -- files to include, and omit
• Branching patterns -- what they are, and how to choose one
• Maintenance strategies -- how to keep your local repository up-to-date
• Access control -- ensuring the right people have the write access

The Good

Git truths you need to internalise:

• Git is a very good content tracker for text files.
• Git is very fast compared to centralized VCS.

The Bad

Git core will not solve all of your problems:

• Git is not a dependency manager.
• Git takes whole file snapshots.
• Git is not optimised for tracking binary files.
• Git does not include in-repository access control.
• Git becomes slower as your history gets very, very large.

The Ugly

Git is notorious for its "holy wars".

This makes it seem very complicated and hard to learn.

This presentation unpacks the rationale behind the most common arguments.

Repository Architecture

Important questions:

• How do you manage dependencies?
• Where do you store very large files?
• How do optimise your build process for very fast deployments?

Dependency Management

• "Vendor branches" -- named branches for upstream work
• Version your build manifest
• Subtrees -- nest repositories without tracking
• Submodules -- nested repositories with hierarchical tracking

Microservices or Monolith

Monolith:

• Consider your audience: if you don't need to scale, and it's easier for your team, use a single repository to store all knowledge for a project.
• If you don't know exactly what you're building, stick to one repo for your code.
• If the language you're working in doesn't have a package manager, consider using one repo for deployments.

Microservices:

• Think OOP: For separate functionality, use separate repositories.
• Pull together related pieces at build time.

Very Large Files

• Compiled dependencies: i.e., libraries your program needs to run
• Asset binaries: e.g., source files for images, video files

Use Offsite Storage for Very Large Files

Do not version binaries in the repository; reference them from another location.

• git-annex
• git-bigfiles
• GLFS

Use Shallow Clones for Faster Deployments

Avoid grabbing all versions of a file for the deployment.

$ git clone --depth [depth] [remote-url]

$ git clone [URL] --branch [branch_name] --single-branch [folder]

Branching Patterns

Important questions:

• How do you separate your work in progress from fully tested, approved work?

Popular Branching Conventions

• Scheduled Release (GitFlow)
• Branch-Per-Feature (GitHub Flow)
• State / Environment Branching (GitLab Flow)

Scheduled Release

Branch-Per-Feature

State Branching

Choose and Use a Strategy

• Pick a branching strategy which suits your deployment schedule.
• It doesn't really matter which strategy you use.
• Document the exact steps people should use. Ensure documentation is followed.

Maintenance Strategies

Important questions:

• How do you incorporate upstream work? aka How do you bring branches up to date?
• How do you combine newly approved work into your project's stable branch?

Why the Fuss?Because TIMTOWTDI

• pull => fetch + merge
• pull --rebase=preserve => fetch + rebase
• merge --no-ff => forces a merge commit object (“true merge”)
• merge --ff-only => fast forward (graph looks like rebase)
• merge --squash => compress commits to one; then merge
• rebase => forward-port local commits
• cherry-pick => merge individual commits

Merging to Update is "Messy"

Merge Commits to Combine are "Messy"

Commit to Whole Thoughts

Reshape commit objects so that they are:

• just the right size
• contain only related code
• conforming to coding standards

$ git rebase --interactive HEAD~n

Resources: gitforteams.com/resources/commit-granularity.html

Convert Conversations to Conclusions

• If the review process has resulted in additional commits, squash these commits into logical conclusions.

Prior to merge:

$ git rebase --interactive HEAD~n

At merge:

$ git merge --squash NNNN-pull_request_branch

Access Control

Important questions:

• Who gets write access?
• What can they commit to?

Per-Branch Permissions & Restrictions

• aka The Subversion Way
• now available from GitLab, and Bitbucket

Pull Request Model

• aka The GitHub Way
• available everywhere

Centralised Systems

Basic Setup with Central Repo

"Ancient" Patching Workflow

Forking Workflow -- Pull Requests

Forking Workflow -- Example

All Access Workflow

Summary

• Repository architecture -- include only what you can't build
• Branching patterns -- what they are, and how to choose one
• Maintenance strategies -- how to keep your local repository up-to-date
• Access control -- ensuring the right people have the write access

Best Practices

Repository Architecture

• Store very large files outside of the repository.
• Speed up deployments with shallow clones.
• Use a single repository when individual services aren't known.
• Create stand-alone repositories when you can identify discrete operations.

Best Practices

Branching Patterns

• Choose and use a strategy that suits your deployment model.
• e.g. GitFlow, GitHub Flow, GitLab Flow
• aka Scheduled Deployments, Branch-per-Feature, Environment/State Branching

Best Pratices

Maintenance Strategies

• When submitting work for review: Commit to whole thoughts.
• When merging work: Convert conversations to conclusions.

Best Practices

Access Control

• Choose and use a strategy that suits your governance model.
• Per-repository access with pull requests is typical; per-branch is becoming more common.
• e.g. Patching, Forking, All Access.

gitforteams.com

Emma Jane Hogbin Westby

@emmajanehw

emmajane.github.io/git-team-setup-overview

Resources

Big Repositories

• How to Handle Big Repositories with Git
• HackerNews: How do you handle your microservices
• StackExchange: How do you handle external dependencies?
• Organizing Microservices in a Single Repository

Dependency Management

• Paket for .NET and Mono
• Composer for PHP

Submodules

• Mastering Submodules