Repositories, Branches, and Pull Requests

Published · Updated

A repository stores a project’s files and version history. A branch is a movable name for a line of commits. A pull request is a GitHub collaboration feature for proposing that changes from one branch be reviewed and merged into another. Understanding those different jobs makes the command line and GitHub interface much less mysterious.

Git and GitHub are different layers

Git is the distributed version-control system on your computer. It can initialize a repository, create commits, make branches and merge them without GitHub or an internet connection.

GitHub hosts Git repositories and adds collaboration features such as pull requests, reviews, issues, permissions and automated checks. A local repository and a GitHub repository can exchange commits through a configured remote, commonly named origin.

That gives you a useful mental model:

Working files → staged changes → local commit → local branch
                                           ↕ fetch / pull / push
                                  branch on a GitHub remote
                                           ↓
                                     pull request

Repository: the project and its history

A Git repository contains snapshots called commits plus references that help you navigate the history. Your working directory contains the files you can edit; Git’s staging area lets you choose what will enter the next commit.

Three commands answer three different questions:

git status              # What changed, and what is staged?
git diff                # What unstaged content changed?
git diff --cached       # What will the next commit contain?

A GitHub repository is a hosted copy with its own visibility and access rules. Cloning it creates a local repository and normally adds the source as the origin remote:

git clone https://github.com/OWNER/REPOSITORY.git
cd REPOSITORY
git remote -v

Commit: a reviewable unit of history

A commit records a chosen set of changes with author information, a timestamp, a message and a link to its parent commit or commits. Good commits are focused enough to explain and test.

git add src/example.java
git diff --cached
git commit -m "Handle an empty search query"

Committing is local. It does not automatically upload anything to GitHub; git push transfers reachable commits to a branch on a remote repository.

Branch: a name that moves with new commits

A branch lets you develop a feature or fix from an existing point without immediately changing the default branch. Git’s current command for creating and switching to a branch is:

git switch -c fix/empty-search

As you commit, the branch name advances to the newest commit. Other branches do not receive those commits until you merge, rebase or otherwise integrate them. The Git switch manual documents branch creation and switching.

On GitHub, the default branch is the branch shown first and normally used as the base for new pull requests. GitHub currently names the default branch main for new repositories, although an existing repository may use another name. Always inspect the repository instead of assuming. GitHub’s branches reference explains default branches and protected branches.

Remote-tracking names are not local branches

After fetching, origin/main represents your local view of the remote’s main branch at the last fetch. Your local main is a separate branch. This is why collaboration often begins with:

git switch main
git pull --ff-only
git switch -c feature/add-health-check

git fetch downloads remote updates without integrating them into your current branch. git pull fetches and then integrates according to your configuration and options. Beginners should inspect git status and their repository’s workflow before resolving divergence.

Pull request: a proposal, not a Git object

A pull request proposes merging changes from a head branch into a base branch. It gives collaborators a place to read the diff, discuss lines, run checks, request changes and record the merge decision. The commits and branches exist in Git; the pull request itself exists on GitHub.

For a typical feature:

  1. Start from the repository’s current default branch.
  2. Create a topic branch.
  3. Make and test focused commits.
  4. Push the topic branch to GitHub.
  5. Open a pull request with the topic branch as head and the intended destination as base.
  6. Respond to review and checks by pushing more commits to the same branch.
  7. Merge when the repository’s requirements are satisfied.

GitHub’s pull-request documentation describes this lifecycle. Opening a PR does not by itself guarantee review, passing tests or safe code; repository rules and team practice determine what is required.

A small example

Suppose main contains a working API and you need to add a health endpoint:

git switch main
git pull --ff-only
git switch -c feature/health-endpoint

# Edit and test the project
git status
git add src test
git diff --cached
git commit -m "Add API health endpoint"
git push -u origin feature/health-endpoint

On GitHub, compare feature/health-endpoint into main, explain why the change is needed, include how you tested it, and request review. If a reviewer asks for a test, add it locally, commit and push; the same PR updates automatically.

Common misconceptions

  • “A branch is a copy of the whole folder.” Conceptually it gives you another line of work, but Git represents branch names as references to commits.
  • “A commit is already backed up on GitHub.” Not until it has been pushed to a remote.
  • “A pull request downloads code.” Fetching or pulling transfers commits; a PR is the hosted proposal and review conversation.
  • “main is always the default.” It is GitHub’s default for new repositories, but repository owners can choose another branch.
  • “A PR approval always blocks or permits merging.” Enforcement depends on branch protection or rulesets and the reviewer’s permissions.

Practise the workflow

Use the end-to-end GitHub workflow tutorial when you are ready to create and merge a practice PR. If you already have a local application, follow the safer path for linking a Spring Boot project to GitHub. For shared repositories, continue with branch protection rules and rulesets.

Repository literacy is one part of delivering software with a team, which is why it also appears in the Forward-Deployed Engineer program.