| name | devtools-version-control |
| description | Use when starting a new task, creating a branch, switching branches, managing branches, creating and uploading CLs, handling stacked changes, or checking release and roll status in the DevTools Gerrit-based workflow. ALWAYS use this instead of running standard git checkout/switch commands for branch creation. |
DevTools Version Control
[!IMPORTANT]
DO NOT use standard Git commands like git checkout -b or git switch -c to create branches.
In Chrome DevTools, you MUST always use git new-branch <branch-name> (or git new-branch --upstream_current <branch-name> for stacked CLs). Standard commands fail to configure the correct upstream tracking branch required by depot_tools and Gerrit.
Overview
Chrome DevTools uses Gerrit for code review. The standard workflow is one branch per Change List (CL) and one commit per branch. Instead of multiple commits, you amend your single commit locally.
Core Workflow
Creating a New CL
To start a new task, create a new branch from main:
git new-branch <branch-name>
Note: This automatically sets the upstream to origin/main.
Making Changes
- Make your changes.
- Stage them:
git add <files>.
- Create the commit:
git commit -m "Your message".
Updating a CL (Amending)
To update your CL after feedback or more work:
- Make more changes.
- Stage them:
git add <files>.
- Amend the commit:
git commit --amend.
Stacked CLs
If CL B depends on CL A:
- While on branch A, create branch B:
git new-branch --upstream_current <branch-B>
- Develop on branch B.
- When uploading B, Gerrit will show the dependency on A.
Reparenting
If you need to change the base of a branch (e.g., move CL B to be based on main instead of CL A):
git reparent-branch main
Or to make it depend on another branch C:
git reparent-branch <branch-C>
Syncing with Upstream
To update all your branches with the latest changes from main and their respective upstreams:
git rebase-update
Initial upload
When a CL is ready, upload it with:
git cl upload -f -d --commit-description="<description>"
- Always include
-f (--force) so that git cl upload runs non-interactively without opening a text editor or prompting.
- Use the same writing style as the current committer
- Keep line length below 72
- Add a "Bug: " or "Bug: None" trailer on a separate line.
- Amend formatter/linter changes and fix linter issues.
Subsequent upload
To upload an updated CL:
git cl upload -f -d -t "<one sentence patch set description>"
Release and Roll Status
To check whether a DevTools commit (devtools/devtools-frontend) has rolled into chromium/src (Roll status) and what version or channel it is deployed to (Release status), look it up via the Chromium Dash API:
https://chromiumdash.appspot.com/fetch_commit?commit=<sha>
Quick Reference
| Action | Command |
|---|
| Create new CL from main | git new-branch <name> |
| Create stacked CL | git new-branch --upstream_current <name> |
| Update current CL | git commit --amend |
| Upload to Gerrit | git cl upload -f |
| Change branch parent | git reparent-branch <new-parent> |
| Sync all branches | git rebase-update |
| Check release & roll status | Query https://chromiumdash.appspot.com/fetch_commit?commit=<sha> |
Common Mistakes
- Multiple commits on one branch: Gerrit expects one commit per CL. Always
commit --amend.
- Using
git checkout -b: Does not set up tracking information correctly for depot_tools. Use git new-branch.
- Manual rebasing of stacked branches: Can be complex. Use
git rebase-update or git reparent-branch to let depot_tools handle the tracking updates.
