GitHub Fork 門派修煉指南：從無名小卒到開源大俠的六式心法

Prologue: The Initiation Rite of Open Source

In the world of open source, many know how to write code — few know how to collaborate.

You spot a great project on GitHub. You’re impressed, you want to contribute. But then you check — no push permission. It’s like walking up to the Shaolin Temple, thinking the kung fu looks awesome, only to find the gates are locked.

What you need is a Fork.

A fork creates a complete copy of someone else’s repo under your own account. You get full read-write access, can modify freely, and submit changes back to the original project via Pull Request. In short: copy the master’s manual, practice at home, then return to demonstrate your new moves.

bxservice/idempiere-rest  (upstream, the original school)
        │
        └── fork ──→  your-account/idempiere-rest  (your training ground)

This article walks you through the complete Six Moves of Fork collaboration, from joining the school to standing on your own. All commands are battle-tested. Copy, paste, conquer.

Move 1: Join the School — Creating a Fork

Mantra: “To master the art, first copy the manual.”

The first step in joining a martial arts school is to get your own copy of the master’s manual (repo).

Basic Usage: Fork to Personal Account

# If you've already cloned the original repo, run from that directory
gh repo fork bxservice/idempiere-rest

# If you haven't cloned yet, add --clone to clone it as well
gh repo fork bxservice/idempiere-rest --clone

This will:

1. Create a fork under your GitHub account
2. Automatically add a fork remote on your local machine

Congratulations, you’ve got the manual. But don’t start practicing yet — you need to pick your training ground first.

Move 2: Choose Your Training Ground

Mantra: “Different mountains, different rules.”

You can fork to your personal account or to an organization. Think of it as choosing between practicing in your backyard or at the company dojo.

Fork to an Organization

gh repo fork bxservice/idempiere-rest --org topgiga

This creates the fork at topgiga/idempiere-rest instead of your personal account.

Scout First: Check if Someone Already Forked

GitHub only allows one fork per org/user. Like a school that only keeps one copy of each manual. Check before creating:

# Method 1: Check if the repo exists and is a fork
gh api repos/topgiga/idempiere-rest --jq '.fork' 2>/dev/null && echo "exists" || echo "doesn't exist"

# Method 2: List all forks of the upstream
gh api repos/bxservice/idempiere-rest/forks --jq '.[].full_name'

What If the Org Already Has a Fork?

If topgiga/idempiere-rest already exists, you have three options:

Option 1: Share the existing fork (most common)

The whole org shares one fork, each person pushes their own branches. Like fellow students sharing one manual, each adding their own notes:

git remote add topgiga https://github.com/topgiga/idempiere-rest.git
git push topgiga feature/my-branch

Option 2: Use your personal fork

Submit PRs from your personal fork — works just as well. Practice solo, no interference:

gh repo fork bxservice/idempiere-rest
git push fork feature/my-branch

Option 3: Create a regular repo

Not recommended. Breaks the link with upstream, can’t submit PRs directly. Like leaving the school to start your own — sounds cool, but you can’t spar with your old classmates anymore.

Move 3: Create Your Own Technique — Development

Mantra: “Learn from the master, innovate on your own.”

Manual acquired, training ground chosen — now it’s time to develop new techniques based on the master’s foundation.

Verify Remote Setup

First, check that your communication channels are clear:

git remote -v

You should see:

origin  https://github.com/bxservice/idempiere-rest.git   (upstream, read-only)
fork    https://github.com/your-account/idempiere-rest.git (your fork, read-write)

Create a Feature Branch and Develop

# Create a training branch for your new technique
git checkout -b feature/my-feature

# ... develop, commit ...

Push to Your Fork

# Push your perfected technique to your training ground
git push fork feature/my-feature

Your new technique is ready, stored safely in your training ground. Now it’s time to return to the school and show the master.

Move 4: The Tournament — Pull Request

Mantra: “Even the finest technique is nothing until the master approves.”

A Pull Request is you returning to the school to demonstrate your new technique to the master (maintainer). If the master approves, your technique gets added to the official manual.

gh pr create --repo bxservice/idempiere-rest \
  --title "Add my feature" \
  --body "Description of changes"

This creates a PR from your-account:feature/my-feature to bxservice:master.

Once the master (e.g., Carlos) reviews and approves, it gets merged into upstream master. Your technique is now part of the school’s official curriculum.

Addressing Review Feedback

The master rarely approves on the first try. They might say: “Your stance is sloppy” or “There’s an opening in your defense.” Fix it and push again — the PR updates automatically:

git add .
git commit -m "Address review feedback"
git push fork feature/my-feature

Squashing Commits If Required

The master may ask you to consolidate your scattered fixes into one clean commit:

git reset --soft $(git merge-base master HEAD)
git commit -m "Add callout endpoint (squashed)"
git push fork feature/my-feature --force-with-lease

Move 5: Return to the Mountain — Sync Upstream

Mantra: “Training alone is no match for learning from the source.”

The school’s martial arts evolve constantly (other PRs get merged). You need to return periodically to learn the latest techniques and stay in sync:

# Fetch the latest from upstream
git fetch origin

# Update local master
git checkout master
git merge origin/master

# Sync to your fork
git push fork master

Think of it as visiting the Shaolin library every now and then to check for new manuals — skip this, and your kung fu falls behind.

Move 6: Full Combat Demo — Complete Workflow

Mantra: “Theory fades on paper; only battle reveals true skill.”

Here’s a complete combat sequence using the idempiere-rest project, from enrollment to graduation in one fluid motion:

# 1. Download the original manual
git clone https://github.com/bxservice/idempiere-rest.git
cd idempiere-rest

# 2. Create your fork (auto-adds fork remote)
gh repo fork --remote

# 3. Open a new training branch
git checkout -b feature/callout-endpoint

# 4. Develop, test, commit
git add .
git commit -m "Add callout endpoint"

# 5. Push to your training ground
git push fork feature/callout-endpoint

# 6. Return to demonstrate (create PR)
gh pr create --repo bxservice/idempiere-rest \
  --title "Add callout endpoint" \
  --body "Description..."

# 7. Address master's feedback, push again
git add .
git commit -m "Address review feedback"
git push fork feature/callout-endpoint

# 8. Squash if master requires clean history
git reset --soft $(git merge-base master HEAD)
git commit -m "Add callout endpoint (squashed)"
git push fork feature/callout-endpoint --force-with-lease

# 9. After merge, sync latest from school
git checkout master
git fetch origin
git merge origin/master
git push fork master

# 10. Clean up the training branch
git branch -d feature/callout-endpoint
git push fork --delete feature/callout-endpoint

Q&A: Wisdom from the Elders

Q: What’s the difference between Fork and Clone?

Fork is a GitHub operation — creating a copy of a repo under your account. Like registering at the school office to get your own copy of the manual. Clone is a Git operation — downloading the repo to your local machine. Like carrying that manual back to your practice room.

You usually need both: fork first (copy the manual), then clone (bring it home).

Q: Can I submit a PR from my fork to any repo?

Only to repos within the same fork network — the upstream and all its forks. You can spar with fellow students, but you can’t take Shaolin techniques to challenge Wudang.

Q: Does my fork auto-sync when upstream updates?

No. You need to manually fetch + merge (see “Move 5: Return to the Mountain”). The master doesn’t deliver new manuals to your doorstep — you have to go get them yourself.

Q: Can I delete my fork?

Yes. Go to GitHub repo Settings > Danger Zone > Delete this repository. Deleting your fork doesn’t affect upstream — leaving the school doesn’t shut it down. But any unmerged PRs will become invalid. Make sure your techniques are recorded before you leave.

Workflow Diagram

upstream (the school)             fork (your training ground)     local
      │                                │                          │
      │                                │   git clone / fetch       │
      │                                │ ◄───────────────────────► │
      │                                │                          │
      │                                │   git push fork          │
      │                                │ ◄──────────────────────  │
      │                                │                          │
      │   Pull Request (tournament)    │                          │
      │ ◄───────────────────────────── │                          │
      │                                │                          │
      │   after merge (into canon)     │                          │
      │ ──────────────────────────────►│                          │

Ray Lee’s Verdict

Ray Lee writes: “I have observed the world of open source, and its way is like the martial arts world. To fork is to join a school and copy the manual; to branch is to create new techniques; to PR is to return and demonstrate; to merge is to enshrine a technique in the canon. Those who know not the way of Fork possess great coding skill but nowhere to wield it — lone wolves with legendary abilities but no school to call home. Master these six moves, and you shall roam the open source world freely, sparring with the greatest, and become a true master.”

May you find your school in the open source world, and forge your own legendary technique.