Brave Sync Process Explained: How to Use npm run sync Commands

The Brave sync process is a build-time routine that fetches the latest Chromium and brave-core revisions, applies Brave-specific patches, updates the DEPS file, and runs post-fetch hooks to prepare the multi-repository codebase for compilation.

The brave/brave-browser repository orchestrates a complex build system that depends on several large sub-projects, including Chromium and brave-core. Instead of manually managing these dependencies, developers use the Brave sync process through npm run sync commands to automatically fetch code, apply patches, and synchronize versions across the entire tree.

What Is the Brave Sync Process?

Brave Browser is constructed from multiple independent repositories. The sync process is a Node.js-based script defined in the repository’s package.json that automates four critical build preparation steps:

1. Fetches the latest revisions of Chromium, brave-core, and helper repositories (or specific refs you designate).
2. Applies Brave-specific patches stored in the repository to adapt upstream code.
3. Updates the src/brave/DEPS file used by Chromium’s gclient tool to ensure dependency versions remain consistent.
4. Runs post-fetch hooks, such as npm install inside child repositories, ensuring the code is ready for compilation.

According to the repository's README.md, npm run sync "updates sub-projects (chromium, brave-core) to latest commit of a git ref … Apply patches … Update gclient DEPS dependencies … Run hooks"【/cache/repos/github.com/brave/brave-browser/master/README.md#L21-L27】.

How to Use npm run sync Commands

The npm run sync command serves as the primary interface for the Brave sync process. Flags are passed after a double-dash (--) to forward them to the underlying script.

Core Sync Flags and Options

Flag	Function	When to Use
(no flags)	Updates Chromium only if its version changed, re-applies changed patches, and updates child dependencies only if a project changed.	Daily development to keep the tree current without forcing full rebuilds.
--force	Forces both Chromium and brave-core to the latest remote commit and re-applies all patches; forces all child dependencies.	When the local tree is corrupted or you need a clean reset to the tip.
--init	Forces Chromium and brave-core to the versions pinned in brave-core/package.json and updates every dependent repo.	Fresh checkouts or after switching major release branches.
--sync_chromium (true|false)	Explicitly forces or skips Chromium version updates.	Skip a large Chromium bump you're not ready to compile.
-D, --delete_unused_deps	Deletes sub-projects removed since the last sync (mirrors gclient sync -D).	Clean up after DEPS changes drop dependencies.
--create	Creates a new sync branch (used by internal tooling).	Advanced workflows for custom branch handling.
brave_core_ref (positional)	Checks out the specified brave-core ref before syncing the rest of the tree.	Pinning specific brave-core versions for reproducible builds.

Command Syntax Examples

Pass flags after the double-dash to ensure they reach the sync script:

# Basic update – minimal work, safe for daily use

npm run sync

# Force reset everything to latest remote

npm run sync -- --force

# Initialize fresh checkout to pinned versions

npm run sync -- --init

# Skip Chromium update (useful for avoiding long rebuilds)

npm run sync -- --sync_chromium=false

# Clean up deleted dependencies

npm run sync -- -D

Where Sync Logic Lives in the Repository

The Brave sync process relies on several key files across the repository:

• README.md – Documents the high-level sync workflow, available flags, and usage examples.
• src/brave/DEPS – The Chromium-style DEPS file listing exact Git repositories and revisions for Chromium, brave-core, and other dependencies. The sync script reads this to determine what to fetch.
• package.json (root) – Declares the sync npm script that serves as the entry point for npm run sync.
• gclient (external tool) – Invoked by the sync script to materialize the dependencies specified in DEPS.
• Patch files (*.patch throughout the repo) – Applied after fetching to inject Brave-specific modifications into upstream code.

According to the repository documentation, the build system "fetches and syncs code from the projects defined in package.json and src/brave/DEPS"【/cache/repos/github.com/brave/brave-browser/master/README.md#L5-L6】.

Common Brave Sync Scenarios

Situation	Command
Create a new feature branch	bash<br>cd src/brave<br>git checkout -b my-feature<br>npm run sync<br>
Update current branch to latest remote	bash<br>git pull<br>npm run sync<br>
Reset to latest brave-core master	bash<br>git checkout master<br>git pull<br>npm run sync -- --init<br>
Only patches changed, no Chromium bump	bash<br>npm run sync<br>
Force clean state after broken sync	bash<br>npm run sync -- --force<br>
Sync to specific brave-core tag	bash<br>npm run sync v1.2.3<br>

Summary

• The Brave sync process is a build-time automation that fetches Chromium and brave-core revisions, applies Brave-specific patches, updates src/brave/DEPS, and runs post-fetch hooks.
• Use npm run sync as the primary command, passing flags after -- to control behavior.
• Key flags include --force (full reset), --init (fresh checkout to pinned versions), --sync_chromium=false (skip Chromium updates), and -D (delete unused dependencies).
• The sync logic is defined in the repository's README.md, orchestrated through package.json, and executes against the src/brave/DEPS file using Chromium's gclient tooling.

Frequently Asked Questions

What does npm run sync actually do behind the scenes?

The command executes a Node.js script that calls gclient sync to materialize dependencies listed in src/brave/DEPS, applies all *.patch files found in the repository to modify upstream code, and executes post-fetch hooks such as npm install in child directories. This ensures Chromium, brave-core, and auxiliary repos are checked out to the correct revisions and ready for compilation.

When should I use --force vs --init?

Use --force when your local tree is in an inconsistent state or you want to reset Chromium and brave-core to the latest remote commits while re-applying all patches. Use --init when performing a fresh checkout or after switching major release branches, as it forces Chromium and brave-core to the specific versions pinned in brave-core/package.json rather than the latest tip.

How do I skip the Chromium update during sync?

Pass the --sync_chromium=false flag after the double-dash: npm run sync -- --sync_chromium=false. This prevents the sync script from fetching a new Chromium revision, which is useful when you want to avoid triggering a lengthy rebuild of the Chromium engine while still updating brave-core or applying new patches.

Where are the Brave patches stored and applied?

Brave-specific patches are stored as *.patch files throughout the repository. During the sync process, the Node.js script automatically discovers and applies these patches to the fetched Chromium and brave-core source trees after gclient sync completes but before running post-fetch hooks. This modifies upstream code to implement Brave-specific features and security enhancements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}