SF Shuttle

Move Salesforce components from your org-connected SFDX project into your team's git repo — with their layouts, permission entries and dependencies — then branch, commit, push and open the pull request, without leaving VS Code.

Many Salesforce teams work with two folders: an SFDX project connected to the org (where you retrieve and deploy) and a separate git repository (where branches, commits and pull requests happen). Moving work from one to the other by hand is slow and error-prone — especially profiles, permission sets and custom labels, where the org copy contains everything but the repo copy is curated.

SF Shuttle automates that move. It works only with files on disk: it never connects to an org (retrieve with the Salesforce extensions as usual) and makes no AI or network calls apart from git.

Features

• Find any component — search every component in your SF project by name, type or status (Region, CustomField, Modified).
• See what changed — each component is marked New, Modified or Unchanged compared to the repo; click to open a side-by-side diff (SF project → repo). A Changes view lists everything that differs.
• Related components, automatically — pick a field and SF Shuttle lists the layouts, list views, LWC / Aura components, permission sets and profiles that use it, plus possible references in Apex, flows and formulas. What's already identical in the repo is hidden.
• Shared files done right — for profiles, permission sets, custom labels, sharing rules, workflows and assignment / escalation / auto-response / matching rules, only the relevant entries (e.g. one <fieldPermissions> or <labels> block) are merged into the repo's file. Everything else stays byte-for-byte identical, so the git diff is just that block.
• Dependencies — a Uses group suggests what a component depends on (an LWC's Apex controller and labels, a field's object, classes an Apex class calls, and the fields an Apex class uses — from SOQL, Account.Field__c, new records and typed variables).
• Start from a profile or permission set — pick one on its own to list only its entries that differ from the repo; tick the ones that belong to your work.
• Go deeper, safely — see what related items connect to (permission set → fields → their layouts) up to 3 levels, with hard limits: never through profiles, permission sets, layouts or objects, only new / changed components, each once, capped per branch and in total.
• Partial changes — bring over individual change blocks with the diff editor's arrows; SF Shuttle commits the repo file exactly as you left it.
• Ship or Commit — pick or create a branch (from the latest origin/main, named by your team's template, e.g. feature/{ticket}/{name}), write the files, commit only those files, push, and open the pull request (GitHub, GitLab, Bitbucket, Azure DevOps).
• Team settings — commit a .sfshuttle.json to the repo so everyone gets the same branch template, base branch, default folder and ignored folders with no setup.
• Multi-package repos — existing components are updated where they live; new components go to the right package folder (following their object or parent, your default folder, or a folder you choose per component), matching each package's own layout. Components found in several package folders are only written in their primary one.
• Repo branch in the status bar — see and switch the repo's branch, create branches, pull and push.

Getting started

1. Open your SFDX project (the folder with sfdx-project.json) in VS Code.
2. Click sf-shuttle: set repo in the status bar and pick your git repo folder.
3. Open the SF Shuttle view in the Activity Bar and click Find Component (🔍).
4. Search for something you changed, e.g. a field, and add it. Its related components appear underneath.
5. Review: click any item to compare it with the repo; untick anything you don't want.
6. Click Ship (🚀) — choose or create a branch, confirm the commit message, then Open Pull Request.

Team settings (.sfshuttle.json)

Optional, in the repo root and committed with it. Every key is optional; anyone's own VS Code settings still take precedence. Create a starter file with SF Shuttle: Create Team Settings File.

{
  "branchNameTemplate": "feature/{ticket}/{name}",
  "baseBranch": "develop",
  "commitMessageTemplate": "{ticket}: {components}",
  "newComponentFolder": "src/core",
  "ignoreFolders": ["src-temp"],
  "pullRequest": { "targetBranch": "develop" }
}

Template placeholders: {ticket} (asked when used), {name} (first component, e.g. Account-Region), {slug} (account-region), {components} (commit messages).

Safety

• Nothing is written until you confirm; Preview What Will Be Written shows the full plan first.
• Ship refuses to run on a repo with unexpected uncommitted changes, and never deletes anything from the repo.
• Shared files (profiles, permission sets, labels, rules) are never overwritten wholesale — only the selected entries are merged. Check Merge Safety verifies the merge against your repo's real files (read-only).
• Pull is fast-forward only; SF Shuttle never creates merge commits on your behalf.

Settings

All but repoPath can also come from the repo's .sfshuttle.json.

Commands

All commands are under SF Shuttle: in the Command Palette — the main ones are Find Component, Ship Ticked Components, Commit Ticked Components (No Push), Preview What Will Be Written, Open Pull Request for Repo Branch, Switch Repo Branch, Pull Repo Branch, Push Repo Branch, Set Repo Folder, Set Default Folder for New Components, Create Team Settings File and Check Merge Safety.

Requirements

• VS Code 1.90 or later
• git on your PATH
• Salesforce projects in source format (sfdx-project.json); the legacy metadata-API format (src/package.xml) is not supported

Notes

SF Shuttle is an independent project and is not affiliated with or endorsed by Salesforce. Salesforce is a trademark of Salesforce, Inc.