Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 78 ยท Remotes and Collaboration

Collaboration Workflows

Compare GitHub flow, Gitflow, trunk-based development and the forking workflow, simulate two developers with two clones, and learn how to choose a workflow for your team.

Git does not tell you how to work together. It gives you cheap branches, merges and remotes, and leaves the rules to you. A workflow is a team agreement on top of those tools: where does new work start, how does it get reviewed, when does it reach the main line, and how are releases and emergency fixes handled?

This lesson walks through the four workflows you will meet in the real world: GitHub flow, Gitflow, trunk-based development and the forking workflow. For the first three you can run a complete simulation inside our sandbox, using a bare repository as the shared server and two or more clones as the developers. By the end you will be able to read a project's branch layout and know why it looks the way it does, and you will have a short checklist for picking a workflow for your own team.

Platform features such as the green "Merge" button, required reviews and CI checks belong to hosting services like GitHub, not to Git. Our sandbox has no network, so we stand in for the button with the command it runs (git merge --no-ff on the server's main), and for a review with git log and git diff. See Pull Requests and Code Review for the platform side.

Simulating a team with two clones

You do not need two computers to practise collaboration. A bare repository plays the server (see Remotes), and every git clone of it is a separate developer with their own working directory and their own idea of history. Moving between the folders (cd ../bob) is the same as switching between two laptops. The only things that connect them are push, fetch and pull, exactly as in real life.

Before the full workflows, here is the smallest possible collaboration: two developers edit different lines of the same file and never talk to each other.

Bash Two developers, one file, no conflict

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bob's first push was rejected (! [rejected] main -> main (fetch first)), because Ada had pushed in the meantime. git pull --rebase replayed his commit on top of Ada's. The two edits touched different lines, so Git combined them without asking anyone: the final file has Ada's new title and Bob's new footer, and the history is a straight line of three commits. Real conflicts only happen when two people change the same lines; see Resolving Merge Conflicts.

GitHub flow

GitHub flow is the simplest widely used workflow, and the right default for web applications that deploy continuously. It has one rule: main is always deployable. Everything else follows:

  1. Create a short-lived branch from main with a descriptive name (add-search, fix-login-redirect).
  2. Commit on it and push it early.
  3. Open a pull request for discussion and review; CI runs on the branch.
  4. When the review is approved and checks are green, merge into main.
  5. Delete the branch and deploy.
TEXT
 main:        o----------------o-----------M---o
               \                            /
 add-search:    o---o---o------------------o
                       (review, CI, fixes)
Bash GitHub flow: branch, review, merge, clean up

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Ada pushed the feature branch; Bob fetched it and looked at what it adds relative to main (git log main..origin/add-search shows two commits, git diff --stat the total change). The --no-ff merge made a merge commit even though a fast-forward was possible, which keeps the feature visible as a bubble in the graph. Afterwards Ada updated main and deleted the branch locally (-d refuses if it were not merged) and on the server. Note the discipline: the feature branch lived for minutes here, and in practice should live for hours or a few days, not weeks.

Strengths: easy to learn, fast feedback, history reads as a list of reviewed changes. Weaknesses: it assumes you can deploy main at any time; it has no answer for supporting several released versions at once.

Gitflow

Gitflow, described by Vincent Driessen in 2010, was designed for software with scheduled, versioned releases (desktop apps, libraries, firmware). It uses two permanent branches and three kinds of temporary ones:

Branch Lives Created from Merged into
main forever every commit on it is a release (tagged)
develop forever main integration branch for finished features
feature/* days to weeks develop develop
release/x.y days develop main and develop
hotfix/x.y.z hours main main and develop

The hotfix and release branches merge into both long-lived branches. Forgetting the second merge is the classic Gitflow bug: the fix exists in production but reappears in the next release. The simulation below walks through one complete cycle.

Bash Gitflow: feature, release and hotfix in one repository

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

--first-parent follows only the first parent of each merge, which hides the side branches and shows the story of a branch. On main you see exactly three releases (v1.0, v1.1, v1.1.1), each a tagged commit. On develop you see the merges of the feature, the release and the hotfix. The git log develop -- fix.txt check proves the hotfix reached develop as well. After the cycle, only the two permanent branches remain.

Strengths: clear structure for versioned products and for maintaining old versions. Weaknesses: heavy. Long-lived branches mean big, painful merges; develop and main drift; it is a poor fit for continuous deployment. Even its author later added a note recommending simpler flows for web apps.

Trunk-based development

In trunk-based development everyone integrates into a single branch, the trunk (main), at least once a day. Branches, if used at all, last hours and are small. Unfinished features are hidden behind feature flags: the code is merged and deployed, but switched off until it is ready. Releases are cut from the trunk, by tag or by a short-lived release branch.

This is the model behind very large continuous-delivery shops. It demands strong automated tests (a broken trunk blocks everybody), but it removes nearly all merge pain, because branches never get the chance to drift apart.

Bash Trunk-based: squash a short branch, rebase, stay linear

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Ada did two work-in-progress commits on a throwaway branch, then used git merge --squash to land them on main as one commit (the squash output ended with create mode 100644 checkout.txt, and the commit message is hers to write). Bob's commit arrived in between; git pull --rebase put his work on top. The result is a history of three commits in a straight line, with no merge commits and no WIP noise. Squash merging and rebase merging are how most trunk-based teams keep main readable; the pull-request lesson compares them with real merge commits.

Strengths: minimal merge pain, fast integration, matches continuous delivery. Weaknesses: needs good tests, feature flags and a team culture of small changes.

The forking workflow

In open-source projects you usually cannot push to the main repository at all. Instead:

  1. You fork it: a server-side copy that you own (your origin).
  2. You clone your fork and add the original project as a second remote, conventionally upstream.
  3. You work on a branch, push it to your fork, and open a pull request from your fork to the original.
  4. A maintainer reviews and merges it. You pull upstream/main to keep your fork current.

The key idea is that nobody needs write access; the maintainers keep control of the central repository. The mechanics (two remotes, syncing, rebasing a stale pull request) are the topic of Forks, Upstreams and Contributing. Companies sometimes use forks internally too, when they want strict review boundaries.

Patches by email: the mailing-list workflow

The oldest workflow of all needs no server, no fork and no pull request: contributors send patches by email and maintainers apply them. The Linux kernel, Git itself and many other projects still work this way. Everything rests on four commands.

  • git format-patch turns commits into patch files, one per commit, each looking like an email: author, date, Subject: [PATCH n/m] ..., the commit message, then the diff. --cover-letter adds a 0/n file where you describe the whole series; -v2 numbers a revised series ([PATCH v2 1/2]); -o dir chooses the output folder.
  • git send-email mails those files through an SMTP server. It is configured once with sendemail.smtpServer, sendemail.smtpUser, sendemail.smtpEncryption and sendemail.from, and used like git send-email [email protected] outbox/*.patch. Add --dry-run to see what would be sent, and --annotate to edit each message first. It needs an SMTP account and the git-send-email package (a Perl script), so it is shown read-only here.
  • git apply applies a diff to the working tree and creates no commit. --stat summarizes it, --check tests whether it would apply, and --3way falls back to a three-way merge.
  • git am ("apply mailbox") applies patch files as commits, keeping author, date and message. It also accepts a whole mailbox saved from an email client. If a patch fails, it stops: fix the files and run git am --continue, skip with --skip, or restore everything with --abort. --3way retries with a merge when the blobs are available.

A maintainer then reviews by replying to the email, the contributor sends v2 with fixes (the cover letter says what changed), and finally the maintainer applies the series. A related command, git request-pull, prints a summary asking someone to pull from your public repository, which is the "pull request" the kernel community used before the web.

Bash Send a revised series as patches and apply it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Notice that Bob's commits keep Ada as author while Bob is recorded as committer, the same split you saw in Recipes. The cover letter has no diff, so it is skipped when applying. A patch that touches lines Bob has changed since the fork point fails with patch does not apply; the contributor should rebase on the maintainer's current branch and send a new version.

Mailing-list etiquette matters as much as the tools: send plain-text email, one logical change per patch, a subject that completes the sentence "this patch will...", and an honest v2, v3 history in the cover letter. You do not need a mail client for any of it. A web forge's pull request is just a friendlier front end for the same idea.

Release branches and hotfixes without Gitflow

You do not need the whole of Gitflow to support released versions. A common lightweight pattern: work on main as in GitHub flow; when you ship 2.3, tag it, and create a release/2.x branch only when you must patch an old version. Fix the bug on main first, then bring it to the release branch with git cherry-pick -x <commit> (see Cherry-Pick), tag v2.3.1 there and publish. Fixing on main first means you cannot forget the fix in the next release.

Choosing a workflow

Start with the simplest one that works, and add structure only when a real problem demands it.

If your team... Consider
deploys a web service several times a day trunk-based or GitHub flow
is small, wants reviews, uses a hosting platform GitHub flow
ships versioned products and supports old versions GitHub flow with release branches; Gitflow if you really have scheduled releases
accepts contributions from strangers forking workflow
has weak automated tests GitHub flow with mandatory reviews, before going trunk-based

Whatever you choose, these habits matter more than the name:

  • Keep branches short-lived and small. The longer a branch lives, the harder the merge.
  • Sync often. Pull or rebase onto main daily so conflicts arrive in small pieces.
  • Protect main. Require reviews and passing checks; forbid force pushes (Signing, Credentials and Security).
  • Write down the rules (branch names, merge method, release steps) in a CONTRIBUTING file. A workflow nobody remembers is not a workflow.
  • Agree on merge versus rebase and set pull.rebase for everyone, as in push, pull and Tracking Branches.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the central rule of GitHub flow?

    GitHub flow has one long-lived branch, main, which must always be in a deployable state. All work happens on short branches and enters main through reviewed pull requests.
  2. 2. In Gitflow, which branches must a hotfix be merged into?

    The hotfix fixes production (main, then tagged), and it must also land on develop, or the bug returns in the next release.
  3. 3. How does trunk-based development ship unfinished work safely?

    Code is integrated into the trunk continuously, but a flag keeps the new behaviour switched off until it is ready.
  4. 4. In the forking workflow, what is the usual name for the remote that points at the original project?

    origin is your own fork (what you cloned); upstream is the original repository you sync from and open pull requests against.
  5. 5. Two developers change different lines of the same file. What happens when the second one runs git pull --rebase?

    Conflicts need overlapping changes. Edits to different regions merge cleanly, and the rebase replays the second developer's commit on top of the first.

Summary

  • A workflow is a team agreement built on Git's branches, merges and remotes; Git itself does not enforce one.
  • You can simulate a whole team with a bare repository and several clones.
  • GitHub flow: one deployable main, short-lived branches, pull requests. Best default for web projects.
  • Gitflow: main, develop, feature, release and hotfix branches; suited to versioned releases but heavy. Hotfixes and releases merge into both long-lived branches.
  • Trunk-based development: integrate into main daily, hide unfinished work behind flags, keep history linear with squash or rebase merges.
  • The forking workflow gives contributors their own copy (origin) and keeps the original as upstream.
  • Prefer small, short-lived branches, frequent syncing and protected main, whichever workflow you choose.

Next: Pull Requests and Code Review