Git Collaboration Workflow¶

Multi-person, multi-remote workflows: clone, branch, open PRs, merge. Commands: Git Command Set; messages: Commit Conventions.

See also: Git Command Set · Commit Conventions · Gitignore & Hooks

How to read this page¶

1. Concepts — remotes, branches, and PRs in teamwork
2. Overview — workflow models, naming, commands vs steps
3. Scenarios — clone through merge, with pitfalls
4. Symptom lookup — at the bottom

What “collaboration” means in Git¶

Collaboration means many people contribute to one history, usually via a host (GitHub, GitLab, Gitee), branches for in-progress work, and Pull Requests (Merge Requests) for review before landing on main.

In plain terms: “Everyone commits on their own branch, then merges into shared main through the remote and PRs—safely.”

Effect: main (or master) represents integratable code; feature branches can be pushed and rewritten (when solo) until CI and reviewers approve merge.

Overview¶

Common workflow models¶

Follow the target repo’s CONTRIBUTING doc; below covers the most common shared repo + feature + PR and fork + upstream paths.

Remote and branch naming (conventions)¶

Git commands used in this doc¶

PR lifecycle (platform-agnostic)¶

Create branch → commit locally → push branch → open PR/MR
    → CI → review comments → push more commits (same branch updates PR)
    → approve → merge (merge / squash / rebase)
    → delete remote feature branch → switch to main and pull

Post-merge message shapes: Commit Conventions — PR merge.

Scenario: first clone as a repo member¶

Typical uses: Company project; you were added as collaborator.

git clone git@github.com:ORG/APP.git
cd APP

git remote -v

git switch main
git pull origin main

In plain terms: “origin is the team repo—update main, then branch.”

Effect: Avoid committing directly on main unless the team explicitly allows it.

Scenario: fork an OSS project and add upstream¶

Typical uses: No write access; you forked on GitHub and cloned your fork.

git clone git@github.com:YOUR_NAME/APP.git
cd APP

git remote add upstream git@github.com:ORG/APP.git
git remote -v

git fetch upstream
git switch main
git merge upstream/main

In plain terms: “Push to origin (fork); open PRs into upstream (canonical).”

Scenario: sync main before new work¶

Typical uses: Overnight gap; others merged while you were away.

git switch main
git pull origin main

# Fork workflow:
git fetch upstream
git merge upstream/main
git push origin main

In plain terms: “Refresh local main before cutting a new branch.”

Scenario: feature branch development¶

git switch main
git pull origin main

git switch -c feature/oauth-login

git add .
git commit -m "feat(auth): add OAuth callback handler"
git commit -m "test(auth): cover OAuth error paths"

In plain terms: “One feature, one branch—multiple commits OK if each is clear.”

Scenario: push branch and open a Pull Request¶

git push -u origin feature/oauth-login

# On the host: open PR targeting upstream/main (fork) or origin/main (member repo)
# Write PR title per commit conventions—squash merge often uses it as final subject

After review:

git add .
git commit -m "fix: address review comments on token expiry"
git push

Scenario: update a long-lived branch with latest main¶

Option A: merge (simple, may add merge commit)

git switch feature/oauth-login
git fetch origin
git merge origin/main
git push

Option B: rebase (linear history, may need force push)

git switch feature/oauth-login
git fetch origin
git rebase origin/main
git push --force-with-lease

See Rebase vs merge.

Scenario: choosing rebase vs merge¶

git push --force-with-lease origin feature/oauth-login

Scenario: resolve merge or rebase conflicts¶

git merge origin/main
# CONFLICT (content): Merge conflict in src/app.ts

git status

# Edit conflict markers <<<<<<< ======= >>>>>>>

git add src/app.ts
git commit

# During rebase:
git add src/app.ts
git rebase --continue
# Abort: git rebase --abort

In plain terms: “Git stops so you choose the combined result.”

For merge commits with two parents, see git show.

Scenario: rules on shared branches¶

Mistakes on main: revert with a new commit—see After push.

Scenario: production hotfix¶

git fetch origin
git switch -c hotfix/payment-timeout origin/release/v2.3

git commit -m "fix: handle payment gateway timeout"
git push -u origin hotfix/payment-timeout

In plain terms: “Branch from a stable point—not from half-done feature work.”

Scenario: clean up after PR merge¶

git switch main
git pull origin main

git branch -d feature/oauth-login
git fetch origin --prune

Scenario: push rejected—someone else updated the remote¶

git push origin feature/oauth-login
# rejected (fetch first)

git fetch origin
git merge origin/feature/oauth-login
git push

If main moved, see Update branch.

Quick lookup: symptom → suggestion¶

Command index: Git Command Set.