Changelist

What Is a Changelist?

A changelist (often abbreviated as CL) is a collection of file modifications grouped together as a single logical unit for code review and version control submission. The term originates from Perforce, one of the earliest centralized version control systems, and was adopted and popularized by Google’s internal development infrastructure, where engineers use the Critique code review tool to review changelists before they are submitted to the monorepo.

While a changelist is conceptually similar to a pull request (GitHub) or merge request (GitLab), the term carries specific connotations rooted in centralized version control workflows. In Perforce, a changelist is a numbered container that holds pending file edits, adds, and deletes. The developer works on the changelist locally, submits it for review, and then “submits” (commits) it to the depot (central repository) once it is approved. Unlike Git-based workflows where a pull request merges one branch into another, a Perforce changelist operates within a single branch namespace and is committed atomically.

At Google, the changelist concept has been extended beyond its Perforce origins. Google’s internal monorepo (holding billions of lines of code) uses a custom version control system called Piper, and the review tool Critique manages the review lifecycle for each CL. Google’s engineering practices documentation extensively references changelists and defines best practices around CL size, description quality, and review turnaround time that have influenced the broader industry.

How It Works

In a Perforce-based workflow, a changelist follows a lifecycle that differs from Git-based pull requests:

# Create a new changelist in Perforce
p4 change
# This opens an editor where you describe the changelist

# Edit files and associate them with the changelist
p4 edit -c 12345 src/server/handler.go
p4 edit -c 12345 src/server/handler_test.go

# View the changelist contents
p4 describe 12345
# Change 12345 by alice@workspace on 2026/03/15
#   Edit src/server/handler.go
#   Edit src/server/handler_test.go

# Submit (after review approval)
p4 submit -c 12345

Each changelist has a unique numeric identifier and includes a description written by the author. At Google, changelist descriptions follow a specific format:

First line: Short summary (under 72 characters)

Body: Detailed explanation of what changed and why.
Include context about the problem being solved,
the approach taken, and any trade-offs considered.

Bug: b/123456789
Test: Ran unit tests and integration tests

The review workflow for a changelist mirrors the pull request workflow in several ways:

1. Author creates the CL with a description and adds reviewers.
2. Reviewers examine the diff and leave comments on specific lines.
3. The author addresses feedback by updating the CL with new snapshots (similar to pushing new commits).
4. Reviewers approve (called “LGTM” — Looks Good To Me — at Google).
5. The author submits the CL to the repository.

One key difference from Git-based workflows is that changelists in Perforce and Google’s Piper are inherently linear. There are no merge commits, no branch divergence, and no merge conflicts caused by parallel branches. Each CL is rebased onto the latest version of the trunk before submission, ensuring a clean linear history.

Why It Matters

Understanding changelists is important for several reasons, even for teams that primarily use Git:

• Industry terminology. Many senior engineers, especially those who have worked at Google or in game development (where Perforce is dominant), use “CL” and “changelist” interchangeably with “PR” and “pull request.” Understanding the term prevents miscommunication.
• Trunk-based development. The changelist model is closely associated with trunk-based development, where all engineers commit to a single main branch. This workflow, championed by Google and documented by the DORA research program, is correlated with higher software delivery performance. Teams adopting trunk-based development in Git often use short-lived branches and small PRs that behave similarly to changelists.
• Monorepo workflows. Companies operating large monorepos (Google, Meta, Microsoft) often use changelist-based tooling because it scales better than Git’s branch model for repositories with millions of files. Understanding changelists is essential for engineers working in these environments.
• Code review culture. Google’s CL-based review practices — particularly the emphasis on small CLs, fast review turnaround, and descriptive CL descriptions — have been published in their engineering practices guide and have shaped code review norms across the entire industry.

Best Practices

1. Keep changelists small. Google’s engineering guidelines recommend that a CL should be “the smallest change that constitutes a complete, self-contained improvement.” In practice, this means most CLs modify fewer than 200 lines. Small CLs are reviewed faster, reviewed more thoroughly, and are easier to roll back if they cause issues.
2. Write descriptive CL descriptions. The first line should be a concise summary of the change. The body should explain the “why” — the problem being solved and the approach chosen. This description becomes a permanent part of the version history and helps future engineers understand the rationale behind the code.
3. Separate refactoring from behavioral changes. A CL that refactors code structure while also adding new features is harder to review because the reviewer cannot easily distinguish cosmetic changes from functional ones. Submit refactoring as a separate CL before or after the feature CL.
4. Include tests in the same CL as the code they cover. This ensures that every submitted change is testable and that test coverage does not lag behind implementation. Reviewers can verify that the tests actually exercise the new or changed behavior.
5. Map changelists to Git workflows when communicating across teams. When working with collaborators who use Git, translate terminology: a changelist is a pull request, “submit” is merge, “LGTM” is approval, and “the depot” is the remote repository. This reduces friction in cross-tool environments.

Common Mistakes

1. Creating oversized changelists. A changelist that modifies 50 files across 2,000 lines is nearly impossible to review effectively. Research consistently shows that review quality degrades sharply as the size of the change increases. If a CL grows beyond a few hundred lines, consider breaking it into a sequence of smaller, incremental CLs that can each be reviewed and submitted independently.
2. Treating the CL description as optional. A changelist with a one-line description like “fix bug” or “update handler” provides no context for the reviewer, makes the version history useless for archaeology, and makes it impossible to understand the change months later. Invest the two minutes it takes to write a thoughtful description — future engineers (including your future self) will benefit.
3. Conflating Perforce and Git mental models. Engineers transitioning between Perforce and Git sometimes try to use Git branches like Perforce changelists or vice versa. The two systems have fundamentally different models for branching, merging, and history. Take time to understand the native workflow of the tool you are using rather than forcing patterns from the other system.