Remotes

Every clone is complete; push and pull keep them in step

Your laptopa complete repositoryGitHubthe shared copy, called originA colleague's laptopanother complete repositoryABABgit cloneABCgit commitgit pushCgit pullCEvery clone is a complete repository. Push and pull keep the copies in step.You commit locally, with no network, and nothing leaves your machine until you push. GitHub holdsthe copy that everyone agrees on, named origin by convention. git pull is two steps in one: git fetchdownloads the new commits, and a merge then brings them into your branch.

Commit is local. Push sends, pull receives.

Remotes · Going deeper

Fetch, pull and origin/main

After git fetchABCDmainorigin/mainThe new commits are downloaded. Your branch has not moved.After git pullABCDmainorigin/mainFetch, then merge: here a fast-forward.origin/main is your copy of where main was on GitHub when you last asked.It is a label that only fetch, pull and push move. Fetching is always safe: it changes nothing youare working on, and lets you look at what is coming with "git log main..origin/main" before you merge.

fetch downloads. pull downloads and merges.

Pushing

A push is refused if the remote has commits you lack

On GitHubABEa colleague pushed EYour cloneABCyou committed C✗git pushrejected: GitHub has E, you do notgit pullABCEMyour clone now holds E, joined to C by a merge✓git pushaccepted: GitHub gains C and the mergeA push is refused when the remote has commits that you lack.Accepting it would throw a colleague's work away. Bring their commits into your branch first, thenpush again. git push --force overrides the check and deletes their commits from the shared branch.

Pull first, then push. Force deletes other people's work.

Pull requests

A pull request is a conversation that ends in a merge

Branchoff mainone change,one branchPushto originthe commits goto GitHubOpen PRinto maina title, andwhat and whyChecksautomaticbuild, testsand lintersReviewby a colleaguecomments,then approvalchanges requested: push more commits to the same branchMergeinto mainthen deletethe branchA pull request is a conversation about a branch, and it ends in a merge.It shows the difference between your branch and main, runs the automatic checks and collects commentsline by line. Commits pushed later appear in the same pull request. Keep each one small: a smallchange gets a real review, and a huge one gets a nod. A draft pull request asks for early feedback.

Branch, push, open, checks, review, merge.

Pull requests · Going deeper

Three ways to merge a pull request

Create a merge commitABCDEMevery commit, and the fork,stay visible on mainSquash and mergeABECDSC and D become one commit, S:one commit per pull requestRebase and mergeABECDC′D′every commit is replayedonto main in a straight lineThe merge button offers three ways to land a pull request.All three put the same content on main; they differ in the history they leave. Squashing is popularbecause main then reads as one tidy commit per change. A repository can switch off the ones it does not want.

Merge commit, squash or rebase: same content, different history.

Branch protection

Branch protection makes the platform enforce the rules

maina protected branch:pull request required1 approval requiredchecks must passno force pushesgit push origin maina direct push✗blocked: a pull request is requiredPull request #57approved, one check failing✗blocked: required checks must passPull request #58approved, all checks green✓mergedBranch protection turns team habits into rules that the platform enforces.Nobody, however senior or however hurried, can push straight to main or merge with red checks. ACODEOWNERS file requests the right reviewers automatically, by file path. Rulesets are the newerform of the same rules, and can cover many branches and repositories at once.

No direct pushes, no merging without approval and green checks.

Repository roles · Going deeper · 1 of 2

Five roles decide who can read, triage, push, maintain and administer

RoleAdds, on top of the row aboveStill cannotReadview and clone; open issues and pull requests; comment and reviewchange anything in the repositoryTriagelabel, assign, close and reopen issues and pull requestspush or mergeWritepush to branches that are not protected; merge pull requestschange repository settingsMaintainday-to-day settings: topics, wiki, merge methods, Pagesmanage access or security, or deleteAdmineverything: access, branch protection, visibility, deletionnothing is withheldEach role contains the one above it. Give the lowest role that lets someone do the job.These five exist on repositories owned by an organisation, and are best given to teams, not to people one by one.A personal repository has only its owner and collaborators. An approval counts towards a required review only whenit comes from someone with Write or higher. Triage suits people who manage issues without touching the code.

Read, Triage, Write, Maintain, Admin: give the lowest role that does the job.

CODEOWNERS · Going deeper · 2 of 2

In CODEOWNERS the last matching line wins, not the most specific

# .github/CODEOWNERS* @acme/platform*.tf @acme/infra/docs/ @ana/src/pay/ @acme/payments @benA pull request changesReview is requested fromREADME.md@acme/platforminfra/main.tf@acme/infradocs/setup.tf@ana, not @acme/infrasrc/pay/card.py@acme/payments and @bendocs/setup.tf matches lines 2, 3 and 4. Line 4 is last, so it wins.✓Kept in .github/, the repository root or docs/. The first one found is used.✓An owner must have Write access; a team must be visible.✓With the branch rule "Require review from Code Owners", their approval becomes mandatory.The last line that matches a file decides its owners. Order the file from general to specific.Without the branch rule, CODEOWNERS only requests reviewers, and anyone with Write can still approve. With it, achange under src/pay/ cannot merge until the payments team or ben approves. Patterns follow .gitignore rules, exceptthat a line cannot start with ! to exclude. The organisation and names are a worked example.

Order CODEOWNERS from general to specific: the last match decides.

Issues

An issue says what and why; a pull request says how

Issue #42Login fails on Safariwhat and whyBranchfix-safari-loginPull request #57"Fixes #42"howMerged into mainissue #42 is closedautomaticallyYears later, read it backwardsa line of codeits committhe pull requestthe issueAn issue records what is wrong and why. A pull request records how it was fixed.Linking the two gives every change a reason that can be looked up: git blame leads from a line to itscommit, the commit to its pull request, and the pull request to the issue that asked for it. Labelssort issues, an assignee owns one, and a milestone groups them into a release.

Fixes #42 links the work to its reason, and closes the issue on merge.

Issues · Going deeper

Forks: contributing without write access

Upstreamread only for youYour forkon GitHub: you can pushYour laptopa clone of your forkforkclonepushpull requestA fork lets you propose a change to a repository you cannot write to.It is your own copy on GitHub, linked to the original. You push to the fork and open a pull requestfrom it; the maintainers of the original review it and decide. This is how open source accepts workfrom strangers. Inside a company, where everyone can push branches, forks are rarely needed.

Push to your fork, then open a pull request to upstream.

Lesson complete

You finished “Working together on GitHub”

Nicely done.

Open in a new tab