The change
machine.

01 / Purpose

Git is the machine. Hosts are the factory floor.

Git is an independent, distributed version control system. An ordinary full clone keeps the fetched project history locally, so most work does not need a network connection. GitHub and GitLab add shared hosting, collaboration, policy and automation. They do not replace your shell, and neither owns the Git project.

That split is the difference between “I changed history” and “I asked a website to record a review.” Git's job is content-addressed snapshots, named references (refs), and the protocols that move objects between repositories (Pro Git: What is Git?). A host adds accounts, permissions, issues, reviews, packages and continuous integration and delivery (CI/CD). A green check on a pull request is not a Git object, and a successful git push is not a deployment.

The repository page in a browser is more than a local clone. The host combines a server-side Git repository with database records for issues, checks and access control. Your normal checkout has a working tree and index backed by a local Git directory. Remote-tracking refs such as origin/main are local notes, normally refreshed by fetch, not live views of the server (Working with Remotes). Until you fetch, your laptop can have stale knowledge. Until you push, the server may not know your new commits exist.

02 / History

Design pressure that still shows up in daily commands

Git's shape comes from a concrete break with a proprietary tool, not from abstract elegance. Hosts later wrapped the same object model in social and automated collaboration. Dates below are ones that primary sources state directly.

BitKeeper, then Git (2005)

Early Linux kernel work moved as patches and archives. In 2002 the project adopted BitKeeper, a proprietary distributed VCS. In 2005 the relationship between the kernel community and BitKeeper's vendor broke down, and the free-of-charge status was revoked. That forced the community, and Linus Torvalds in particular, to build a replacement aimed at speed, simple design, strong non-linear branching, full distribution, and efficiency on kernel-scale trees (Pro Git: A Short History of Git). Those goals explain why Git prefers local operation, cheap branches as pointers, and content-addressed objects over a central checkout server.

The canonical git.git tree on kernel.org presents the core plumbing under long-running maintenance associated with Junio C. Hamano (git.git about). The consequence for readers: Git evolved as infrastructure for parallel maintainer workflows, which is why rebases, merges, remotes, and reflogs feel first-class rather than bolted on.

GitHub: from social coding to a development platform

GitHub grew from work begun in 2007 by a small team including Tom Preston-Werner, Chris Wanstrath, PJ Hyett and Scott Chacon (GitHub Turns One!). Chris Wanstrath's “We Launched” announcement on 10 April 2008 marks the public launch. It highlighted commit comments, network graphs and integrations. The lasting design bet was that identity, discovery and conversation could make distributed version control a social workflow without replacing Git's object model.

Microsoft announced an acquisition agreement on 4 June 2018 (Microsoft + GitHub) and completed the acquisition on 26 October 2018. Keep announcement and completion dates separate. Ownership of the hosting business changed; Git itself remained an independent open-source project.

GitLab: self-hosted open source, then an integrated company product

Dmitriy Zaporozhets writes that he started the GitLab open-source project in October 2011 with Valery Sizov because there was no modern open-source tool to run on your own server for day-to-day version control collaboration. In 2012 Sid (Sytse) Sijbrandij emailed that he had started GitLab.com. Zaporozhets joined full time in 2013 (GitLab Blog: farewell from Dmitriy Zaporozhets). A later shareholder letter from Zaporozhets and Sijbrandij frames GitLab B.V. as the commercial entity that releases GitLab, offers paid services, and runs GitLab.com, with an explicit open-source stance toward the tools needed to deliver software (Letter from the shareholders).

The lasting design consequence is vertical integration: Git hosting, merge requests, and CI/CD live in one product surface whose exact stages and tiers depend on edition and plan (GitLab CI/CD docs). Where GitHub historically grew a broad marketplace around Actions and apps, GitLab's early pitch was "run the collaboration stack yourself," then "run more of the delivery stack in the same place." Feature availability still varies by Self-Managed versus GitLab.com versus Dedicated, and by subscription tier.

Hosting grew into delivery

GitLab's former standalone CI repository documents its integration into GitLab 8.0; 7.14 was the last standalone CI version (Original migration README). GitHub's 8 August 2019 announcement added native CI/CD to Actions. Both histories explain today's overlap: a repository host is also a control plane for executing code. Choosing one no longer means choosing whether you get CI at all.

03 / Git model

Snapshots, addresses, and refs you can draw by hand

Git stores snapshots, not a permanent textual diff database. Deltas appear later as pack compression. If you keep that straight, merge, rebase, shallow clones, and LFS stop sounding like magic.

Snapshots first; packs later

Pro Git's core claim is blunt: Git thinks in snapshots of a mini filesystem, with unchanged files stored by reference to prior identical content, and nearly every operation adding data rather than rewriting it in place (Pro Git: What is Git?). Objects begin life "loose." Later, git gc, push paths, or object count pressure can pack them into packfiles that store some objects as deltas against others for space, without changing the logical snapshot model (Pro Git: Packfiles).

Four object types and content addressing

At the bottom, Git is a content-addressable key-value store: an object's identifier hashes its type/length header and content (Git Objects). SHA-1 is the traditional default; Git also supports SHA-256 repositories where enabled. Do not assume every host or tool interoperates with both formats (git-init). A hash identifies content; it is not an access-control decision.

• Blob: file contents only (no path).
• Tree: directory entries mapping names and modes to blobs or trees.
• Commit: pointer to a root tree, zero or more parent commits, author/committer identity strings and timestamps, and a message.
• Tag object: an annotated tag points at another object, often a commit, with tagger metadata, message and an optional signature. A lightweight tag is just a ref and creates no tag object.

A commit therefore captures a full tree snapshot plus ancestry links and attribution metadata. Author name and email are fields inside that object. They are not login credentials. Cryptographic proof that a commit came from a trusted key is a separate signing and verification step (Pro Git: Signing Your Work).

Commit ancestry: a topic branch, then a merge commit M

  A---B---C-------M    <- main (branch ref)
       \         /
        D---E---F      <- feature (branch ref)

Each letter is a commit. Parent links point backward.
M has two parents, C and F. Branches are movable names,
not copied folders. A tag can name a release point.

Branches, HEAD, and detached HEAD

A branch is a lightweight movable pointer to a commit; HEAD usually names which branch tip advances when you commit (Pro Git: Branches in a Nutshell). Checking out a raw commit points HEAD at that commit ID instead of a branch: a detached HEAD. New commits can be created there, but no branch name remembers them until you create or update a ref (git-checkout: DETACHED HEAD).

Index as staging intent

The working tree is your editable checkout. The staging area (index) records the complete proposed next snapshot, including unchanged tracked files; it is not just a bag of changed filenames. git add updates selected entries to the content at that moment. Later edits stay unstaged until you add them again. An ordinary git commit writes the index snapshot, not whatever happens to be visible in the editor (The three states).

Local refs, remote-tracking refs, fetch/pull/push

origin is a conventional remote nickname, not a special central server. Fetch obtains remote objects and normally updates remote-tracking refs without integrating them into your current branch. Pull fetches and then integrates using the configured merge/rebase behavior; git pull --ff-only refuses a divergent integration. Push transfers missing objects and asks the remote to update allowed refs. None uploads uncommitted working-tree edits (Working with Remotes).

Merge, rebase, cherry-pick, squash

Merge combines histories. A fast-forward only advances a ref when the old tip is an ancestor of the new one; a divergent merge can create a commit with multiple parents. Rebase replays commits on a new base, normally changing their identifiers (Rebasing). Cherry-pick applies a commit's change on the current branch and normally creates a new commit (Maintaining a Project). Squashing combines several changes into one commit, whether through interactive rebase or a host's merge strategy (Rewriting History). Rewriting shared commits makes collaborators reconcile new IDs. Preserving ancestry and keeping a concise review history are different goals.

04 / Choose your platform

Choose a host for the work, not a tribe

Git stores history. GitHub and GitLab host collaboration: permissions, reviews, issues, CI, packages, and policy. Both support public and private repositories. Feature tiers and deployment options vary by plan and version, so treat marketing pages as secondary to the product docs for your actual plan.

GitHub Enterprise gives access to both GitHub Enterprise Cloud (hosted by GitHub on github.com or a GHE.com subdomain) and GitHub Enterprise Server (a self-hosted appliance you operate on your infrastructure or a public cloud). See About GitHub for enterprises.

GitLab offers three offerings: GitLab.com (multi-tenant SaaS), GitLab Self-Managed (you install and operate), and GitLab Dedicated (single-tenant SaaS hosted by GitLab). Subscriptions do not transfer between GitLab.com and Self-Managed. See GitLab plans.

Portability limits matter. A git clone retrieves Git objects and configured refs, not every server-side record. It does not move pull requests, merge requests, issue comments, check runs, protected-branch settings, or runner registration. Git LFS stores large file contents on a separate remote and leaves pointer files in Git (Git LFS). An installed LFS client can download content automatically during checkout; otherwise configure it and fetch the assets separately. Even an ordinary LFS checkout is not an archive of every historical LFS object. Plan migrations as Git plus platform export/import plus LFS plus deliberately recreated CI credentials.

05 / A change, end to end

Small-branch review that actually protects main

A practical default: short-lived topic branches, pull or merge requests into a protected default branch, required reviews, and required checks. Policy lives on the host. Mechanisms live in Git.

Protect the default branch

On GitHub, branch protection can require pull request reviews, required status checks (loose or strict “up to date”), conversation resolution, signed commits, linear history, a merge queue, and more. Admins can bypass unless you disallow bypass. See About protected branches.

On GitLab, protected branches control who may merge versus who may push and merge, and can require Code Owner approval. Setting “Allowed to push and merge” to No one while allowing Maintainers to merge forces changes through merge requests. See Protected branches. Required approvals are a tiered feature: Free treats approvals as optional; Premium and Ultimate can require counts and types of approvers (Merge request approvals).

Review the effective rule set, not just one checkbox. Overlapping GitLab rules can permit the more permissive push setting. An impossible approval rule can be auto-approved; policy-created rules behave differently. Keep eligible approvers available, prevent self-approval where appropriate, and test the policy with a low-privilege account before relying on it.

Choose squash, merge, or rebase intentionally

GitHub documents three PR merge strategies: merge commit (preserves branch commits plus an explicit merge point), squash and merge (one commit on the base), and rebase and merge (linear history, new commit SHAs). Squash fits short-lived branches that represent one logical change; long-running branches after squash often replay already-merged history. See About pull request merges.

GitLab project merge methods include merge commit, merge commit with semi-linear history, and fast-forward merge, with separate squash defaults from Do not allow through Require. Semi-linear and fast-forward require the source to be up to date (or rebased) before merge. See Merge methods.

06 / The command line

Shell, Git, and host CLIs are three different tools

Your terminal prompt is not Git. Git is not the hosting API. Host CLIs talk to HTTP APIs with their own credentials.

Three different “prompts” get confused. A shell prompt (a leading $, or Starship/zsh branch and dirty markers) is your shell’s display, not a server command: copy only the command text after it. Ahead/behind markers normally compare local refs, so they can be stale until fetch. A CLI command is what git, gh, or glab actually run. An AI natural-language prompt is model context, not an access-control rule. GitHub and GitLab do not generally control your interactive terminal; CI runners launch shells from job configuration. AI assistants invoke tools under their execution environment’s granted permissions, not authority conferred by a prompt file.

Config scopes, author, auth, signing

Git reads configuration from system, global, local, and optionally worktree scopes, with later values generally overriding earlier ones; command-scoped git -c key=value settings can override those too (git-config). Author identity (user.name / user.email) stamps commits. It is not authentication. Authentication uses SSH keys or HTTPS credentials, often managed by a credential helper. A personal access token (PAT) is a scoped credential, not your commit identity. Signing with GPG, SSH or S/MIME provides evidence that a key signed the commit; it does not prove the code is safe or every attribution field is truthful (Commit signature verification).

gh authentication is independent of Git until you opt into using it as a credential helper (Authenticating with GitHub CLI). glab targets gitlab.com by default outside a repo, follows the Git remote host inside a repo, and can be overridden with GITLAB_HOST (Connect to your GitLab instance). Always name the host when you use Enterprise Server, Self-Managed, or Dedicated.

Safe copyable snippets

Replace the example URL and directory with a repository you may contribute to. These commands assume its default branch is main and a clean starting checkout. Run them deliberately, not as a blind script. They are examples, not claims of a successful network operation.

# Clone once, then enter the new repository
git clone https://github.com/EXAMPLE-ORG/EXAMPLE-REPO.git
cd EXAMPLE-REPO
git fetch origin
git switch -c topic/explain-change --no-track origin/main

# Edit files in your editor, then inspect and select changes
git status
git diff
git add -p
# For a new, untracked file, use: git add path/to/file
git diff --cached
git commit -m "Explain the reason for this change"

# Rebase only your unpublished topic work; resolve or abort conflicts
git fetch origin
git rebase origin/main
# Run the project's checks on the integrated result
git push -u origin HEAD

git diff shows unstaged changes; git diff --cached shows the next commit relative to HEAD. If you edit a file after staging it, those later edits are not automatically included. Avoid rebasing a branch that other people are using.

git status --short --branch
git branch -vv
git remote -v
git config --show-origin --get user.email
git log --oneline --graph --decorate -12

Choose the block for your host. Open a proposal first; merge only after reviewing the diff, required approvals and checks. These commands do not bypass server policy. See the GitHub PR commands, GitLab MR commands and GitLab pipeline status.

# GitHub: in the topic branch's repository
gh auth status
gh pr create --fill
gh pr checks
# After review; if squash is the project's chosen policy:
gh pr merge --squash

# GitLab: in the topic branch's repository
glab auth status
glab mr create --fill
glab ci status --compact
# After review; honors project merge settings:
glab mr merge

07 / From code to delivery

CI YAML runs arbitrary code on runners

GitHub Actions workflows live under .github/workflows/ and react to on: events (Workflow syntax). GitLab CI uses .gitlab-ci.yml with stages, jobs, script, rules, artifacts, and cache (CI/CD YAML syntax reference). In both systems, a runner executes the job as defined: treat pipeline config as production code.

Continuous integration (CI) tests integrated changes early. Continuous delivery keeps a releasable result ready for an approval; continuous deployment automatically promotes qualifying changes. “CD” can mean either, so state which. A green pipeline proves only the jobs that actually ran against the revision they tested.

Hosted runners reduce machine administration, but you still control workflow privileges and dependency trust. Self-hosted runners add control and expose your own network: isolate untrusted jobs, prefer disposable execution environments, and keep privileged deploy runners separate. A container alone is not a complete security boundary.

Build once and promote the same artifact where practical. Record the source commit, build identity and deployed artifact digest. Merge rollback and deployment rollback are different: reverting a commit does not by itself replace a running service, and older binaries may be incompatible with newer database migrations.

# .github/workflows/build.yml
name: build-guide
on:
  pull_request:
  merge_group:
permissions:
  contents: read
jobs:
  build:
    runs-on: ubuntu-latest
    container: node:22-bookworm
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 revision
        with:
          persist-credentials: false
      - run: npm run build

# .gitlab-ci.yml
stages: [build]
build-guide:
  stage: build
  image: node:22-bookworm
  script:
    - npm run build
  artifacts:
    paths: [dist/]
    expire_in: 7 days
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

OIDC and untrusted contributions

Prefer short-lived cloud credentials through OpenID Connect (OIDC) rather than long-lived cloud keys in repository secrets. The job obtains a signed identity token; the cloud validates it and issues limited credentials. GitHub Actions supports OIDC federation; GitLab exposes id_tokens. Constrain issuer, audience, repository/project and allowed branch or environment in the cloud trust policy. A short-lived token with an overbroad trust policy is still dangerous.

Fork contributions are untrusted. Prefer ordinary pull_request workflows with restricted permissions. pull_request_target runs in a more privileged base-repository context and can access base secrets and write-capable tokens, subject to configured permissions and event policies. Checking out and executing the contributor's code there is a “pwn request” hazard. Do not build untrusted code with those privileges. Treat downloaded artifacts and interpolated issue/PR text as untrusted too (Securely using pull_request_target).

08 / Trust & recovery

Ownership, secrets, backups, and adjacent tools

Mechanisms enforce what policy intends. If bypass paths exist for bots or admins, document them as deliberate exceptions.

CODEOWNERS maps paths to reviewers. On GitHub, place CODEOWNERS in .github/, root, or docs/; combine with “Require review from Code Owners” on protected branches (About code owners). On GitLab, search order differs (root, docs/, then .gitlab/), and Code Owner approval must be enabled on the protected target branch (Code Owners). Own the CODEOWNERS file itself.

Protect the files that control trust: CI configuration, dependency manifests, deployment scripts and CODEOWNERS. Use least-privilege job tokens, scoped service identities and environment-specific credentials. Masking a secret in logs does not prevent a malicious job from sending it elsewhere. Separate untrusted build execution from trusted publication.

Backups beyond Git: preserve required Git refs, export supported issue/PR/MR metadata, and back up LFS, packages, settings and recoverable credentials according to the host's supported procedure. An export can omit fields or references; rehearse restoration, not just file creation. A laptop clone is not a disaster-recovery plan for the whole platform.

To undo a shared change, usually create a reviewed git revert commit rather than erasing the branch's history. Reverting a merge requires choosing its mainline parent and affects future merges, so inspect the graph first. Reflog recovery helps only while the relevant local records and objects still exist.

09 / Explain it to someone

Teach it back in ninety seconds

Use this script aloud, then expand with the questions below.

“Git is a local history engine. It stores file snapshots linked by commits; branches are names pointing to commits. You can inspect and commit without the internet. The staging area selects exactly what the next commit will contain. Fetch learns remote history, push shares it, and neither is automatically a deployment.

GitHub and GitLab add the shared workspace: identities, issues, reviews, permissions and automation. A pull request or merge request is a proposal with discussion and checks, not a special Git object. Protect the main branch, keep changes small, and validate what will actually be merged.

Your shell prompt is just a display. Git moves history; gh and glab operate the host's APIs. A name on a commit is not proof of who authenticated. CI executes code on a runner, so treat its permissions as seriously as production access. Deploy a known build with a deliberate recovery plan. Back up the collaboration data separately from Git history.”

10 / FOLLOW THE EVIDENCE

The source library.

Primary documentation, original announcements and first-party histories. The guide synthesizes these sources; workflow recommendations are engineering judgments, not vendor guarantees.

Sources checked for this edition. Features, names, editions and entitlements can change. Check your host version and plan before adopting a control.

1. Pro Git: Getting Started — What is Git? ↗git-scm.com
2. Pro Git: Getting Started — A Short History of Git ↗git-scm.com
3. Pro Git: Git Internals — Git Objects ↗git-scm.com
4. Pro Git: Git Internals — Packfiles ↗git-scm.com
5. Pro Git: Git Branching — Branches in a Nutshell ↗git-scm.com
6. Pro Git: Git Branching — Rebasing ↗git-scm.com
7. Pro Git: Git Basics — Working with Remotes ↗git-scm.com
8. Pro Git: Git Tools — Revision Selection (reflog) ↗git-scm.com
9. Pro Git: Git Tools — Rewriting History ↗git-scm.com
10. Pro Git: Distributed Git — Maintaining a Project (cherry-pick) ↗git-scm.com
11. Pro Git: Git Tools — Signing Your Work ↗git-scm.com
12. git-checkout documentation — DETACHED HEAD ↗git-scm.com
13. git-clone documentation (shallow and partial clone) ↗git-scm.com
14. git-reflog documentation ↗git-scm.com
15. Git Large File Storage ↗git-lfs.com
16. git.git about (kernel.org) — Junio C. Hamano ↗git.kernel.org
17. GitHub Blog: GitHub Turns One! (Tom Preston-Werner) ↗github.blog
18. Satya Nadella: Microsoft + GitHub = Empowering Developers ↗blogs.microsoft.com
19. GitLab Blog: A special farewell from Dmitriy Zaporozhets ↗about.gitlab.com
20. GitLab Blog: Letter from the shareholders ↗about.gitlab.com
21. GitLab Docs: Merge requests ↗docs.gitlab.com
22. GitLab Docs: Get started with GitLab CI/CD ↗docs.gitlab.com
23. GitHub: We Launched (10 April 2008) ↗github.blog
24. Microsoft completes GitHub acquisition (26 October 2018) ↗blogs.microsoft.com
25. git-init: repository object formats ↗git-scm.com
26. Original GitLab CI repository: integration into GitLab 8.0 ↗raw.githubusercontent.com
27. GitHub Actions adds CI/CD (8 August 2019) ↗github.blog
28. About GitHub for enterprises ↗docs.github.com
29. GitLab plans ↗docs.gitlab.com
30. About protected branches ↗docs.github.com
31. Managing a merge queue ↗docs.github.com
32. About pull request merges ↗docs.github.com
33. Protected branches ↗docs.gitlab.com
34. Merge request approvals ↗docs.gitlab.com
35. Merge methods ↗docs.gitlab.com
36. Merge trains ↗docs.gitlab.com
37. git-config Documentation ↗git-scm.com
38. About commit signature verification ↗docs.github.com
39. Authenticating with GitHub CLI ↗docs.github.com
40. Connect to your GitLab instance ↗docs.gitlab.com
41. Workflow syntax for GitHub Actions ↗docs.github.com
42. CI/CD YAML syntax reference ↗docs.gitlab.com
43. OpenID Connect (GitHub Actions) ↗docs.github.com
44. Securely using pull_request_target ↗docs.github.com
45. About code owners ↗docs.github.com
46. Code Owners ↗docs.gitlab.com
47. GitHub CLI: pull request commands ↗cli.github.com
48. GitLab CLI: merge request commands ↗docs.gitlab.com
49. GitLab CLI: pipeline status ↗docs.gitlab.com
50. GitLab: OpenID Connect ID tokens and trust policies ↗docs.gitlab.com
51. actions/checkout: v6 upstream revision ↗api.github.com
52. GitHub-hosted runners and isolation ↗docs.github.com
53. GitLab: CI/CD variable security ↗docs.gitlab.com
54. git-revert: reversing a change without deleting history ↗git-scm.com