Forks and branches
Use a remote, pull request and automated check to propose a reviewable change.
THE IDEA
Two different things that sound alike
A branch is a movable name inside one repository. A fork is a second hosted repository, a full copy under your account, with its own branches. You fork when you are allowed to read a project but not to push to it. You branch to isolate one change, in any repository.
Start
Only the upstream exists. You can read it, but you cannot push to it.
acme/shop (upstream)
learner/shop (fork)
your laptop
Predict first. You click Fork on a project you do not own. Which repository changed?
origin, upstream, and staying current
After git clone of your fork, origin is the fork. By convention you add a second remote named upstream that points at the original, so you can fetch what the maintainers do. You have read access to it but not write access, so pushes go to origin only.
acme/shop (upstream, you cannot push)
learner/shop (your fork, origin)
your laptop
Your fork is up to date with the upstream..
Press a button. Every command runs on real simulated repositories.
git clone https://forge.example/learner/shop.git
git remote add upstream https://forge.example/acme/shop.git
git switch -c fix-typo # one branch per change
git push -u origin fix-typo # to YOUR fork
# later, to catch up:
git switch main && git fetch upstream && git merge upstream/main && git push origin mainChapter context
GitHub hosts repositories and adds collaboration around Git objects. A pull request is a review and discussion mechanism; the commits and branch history still follow Git rules.
TRY IT YOURSELF
Forking is a button on the website; in this simulation your fork https://forge.example/learner/shop.git already exists. The original is https://forge.example/acme/shop.git and you cannot push to it.
- Your fork lives at https://forge.example/learner/shop.git. Clone the FORK (not the original) and go into it
- Teach your clone about the original project by adding a second remote named upstream
- Do the fix on its own branch: create fix-typo, commit a change to README.md, and push it to your fork with upstream tracking
- Find out why you need the fork: try to push fix-typo to upstream and read the error
- The original project moved on. Bring its main into your main (fetch upstream, merge), then push main to your fork so the fork catches up
Branches on the servers
upstream main 3943813 your fork main 3943813
Your clone
Not cloned yet.
Stuck, or something not working? You can come back to it any time.
CHECK YOUR UNDERSTANDING
Does opening a fork edit the upstream repository?
Chapter reference: math, worked example & code
This section belongs to the whole chapter, so it is the same on every lesson in it and may cover a different lesson's topic. The code for the experiment you just ran is inside the experiment itself.
Math and notation
For independent jobs with durations t1 and t2 running simultaneously, ideal elapsed time is max(t1,t2), excluding startup and queueing. A dependency adds a sequential edge and can make durations add instead.
Worked example
A build takes 3 minutes. Two test jobs taking 4 and 6 minutes start after the build and run together. The ideal critical path is 3 + max(4, 6) = 9 minutes, not 13. Real runners can add scheduling overhead.
Reference code
The following example uses the Python standard library and does not call a remote service.
build, tests = 3, [4, 6]
assert build + max(tests) == 9
assert build + sum(tests) == 13
Python examples are provided for study and local execution; this page does not execute Python.
Common mistakes
A green check is evidence for the checks that ran, not proof of every behavior. Forked code must not automatically receive trusted secrets.