Google Apps Script Sync

Google Apps Script Sync lets you review and synchronize Apps Script projects from Visual Studio Code. It is designed for deliberate, manual synchronization: opening a folder or saving a file never uploads or downloads code.

What it does

• Connects a local folder to an Apps Script project using its Script ID.
• Shows whether changes are local, remote, or conflicting.
• Shows a preview before every Push or Pull, including commands started from the Command Palette.
• Groups files as added, modified, or deleted and lets you select individual files or whole groups.
• Opens a side-by-side comparison before you decide what to apply.
• Shows a compact Sync activity history in the sidebar with phase, severity, and safe numeric context; it can be cleared at any time.
• Supports English and Spanish in the side panel and VS Code commands.

Safety first

Push and Pull are never automatic. A save only refreshes the change indicator. Connecting a project also does not download it automatically: use Pull, review the preview, and then apply the files you want. If local and remote content changed since the last successful synchronization, both actions are shown and the panel reports a conflict.

The extension accepts only Apps Script source files:

• *.gs
• *.html
• the root manifest appsscript.json

Other JSON files, JavaScript build files, dependencies, editor settings, and technical folders are ignored. Remote names are validated before anything is written or deleted outside the project folder.

Getting started

1. Open the local folder that will contain your Apps Script project.
2. Open Google Apps Script Sync from the Activity Bar.
3. Select Connect and sign in with Google.
4. Paste the Script ID from the Apps Script project URL.
5. Select Pull, review all remote changes, and choose Apply.

Your Google access and refresh tokens are kept in VS Code Secret Storage. Sign-in uses PKCE and a temporary loopback callback. Synchronization and local setup are disabled in untrusted and virtual workspaces.

Terminal CLI

The npm package provides the equivalent gas and gas-sync commands for Node.js 20 or newer. Both names run the same CLI.

Prefer a visual workflow with previews, per-file selection, diffs, sync activity, and bundled autocomplete? Install Google Apps Script Sync from the Visual Studio Marketplace. The Marketplace extension and terminal CLI are installed separately.

Install from npm

# Inspect the published version and executable aliases.
npm view google-apps-script-sync version
npm view google-apps-script-sync bin

# Install the CLI globally.
npm install --global google-apps-script-sync

# Verify both equivalent command names.
gas --help
gas-sync --help

If gas is not found after installation, open a new terminal and confirm that npm's global executable directory is included in PATH.

Quick start

# Authenticate the independent CLI session in the system browser.
gas login

# Run these commands from your local Apps Script project folder.
Set-Location C:\work\my-gas-project

# Connect this folder. Connecting never performs a Pull.
gas connect YOUR_SCRIPT_ID

# Inspect local changes, remote changes, and conflicts.
gas status

# Preview a Pull without changing local files.
gas pull --dry-run

# Review the preview, confirm, and apply the selected Pull changes.
gas pull

Enable the Apps Script API at script.google.com/home/usersettings and use a Google account that can edit the connected project.

Commands

| Command | Description | | --- | --- | | gas login | Sign in with Google using PKCE, state validation, a temporary loopback callback, and the system browser. | | gas logout | Attempt token revocation and remove the local CLI session. | | gas connect <scriptId> | Write qc_config.json in the project folder without downloading files. | | gas status | Report local changes, remote changes, and conflicts. | | gas push | Preview, select, confirm, and upload local changes. | | gas pull | Preview, select, confirm, and download remote changes. | | gas help [command] | Show general help or help for a specific command. |

Push and Pull options

| Option | Description | | --- | --- | | --project <path> | Use an explicit project root instead of the current directory. | | --files <name,...> | Apply only exact names from the preview; repeatable and comma-separated. | | --dry-run | Print the preview and stop without modifying either side. | | --force | Permit a reviewed overwrite detected against a reliable snapshot. It never skips preview or confirmation. | | --yes | Skip the interactive confirmation; required for non-interactive input. |

Every preview entry is selected by default. Examples:

# Upload only two reviewed preview entries.
gas push --files Code.gs,appsscript.json

# Preview a project without changing the current directory.
gas pull --project C:\work\my-gas-project --dry-run

# Deliberately overwrite reviewed remote changes; confirmation is still required.
gas push --force

# Apply a reviewed Pull in non-interactive automation.
gas pull --project C:\work\my-gas-project --yes

Safety and sessions

Push and Pull are never automatic. Both directions hold a project lock, recheck local and remote fingerprints before applying, preserve deselected pending changes in qc_sync_state.json, and synchronize only .gs, .html, and the root appsscript.json. Push preserves unselected remote files; Pull only writes or deletes selected validated paths.

Structured activity is written to stderr, while previews and final results remain on stdout. Logs include safe phases, counts, HTTP status, and retry context, but never Script IDs, absolute paths, file names, source code, payloads, tokens, URLs, fingerprints, or plan IDs. A rejected access token is refreshed once after HTTP 401; if authentication is still rejected, run gas login again.

The CLI session is separate from VS Code Secret Storage. It is stored at %APPDATA%\google-apps-script-sync\session.json on Windows or $XDG_CONFIG_HOME/google-apps-script-sync/session.json (falling back to ~/.config) elsewhere. The file is atomic and uses restrictive permissions where supported, but it is not encrypted. Protect your operating-system account and run gas logout when the session is no longer needed.

Install from source

Contributors can install the current checkout without publishing:

npm ci
npm test
npm install --global .
gas --help

To avoid a global development installation, run npm run compile and execute node .\out\cli.js ....

How to test the extension

Use a temporary Apps Script project and a disposable local folder. Push and Pull can replace or delete selected files on the destination side, so do not use an important project for the first test.

Install the packaged extension

1. In VS Code, open the Command Palette (Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on macOS).
2. Run Extensions: Install from VSIX....
3. Select google-apps-script-sync-0.0.5.vsix and reload VS Code when prompted.
4. Create or open an empty local folder and mark the workspace as trusted.
5. Enable the Apps Script API at script.google.com/home/usersettings.

Manual test checklist

1. Create a temporary project at script.google.com and copy its Script ID from Project Settings.
2. Open Google Apps Script Sync from the Activity Bar, sign in, and connect the temporary project. Confirm that connecting does not download files automatically.
3. Select Pull. Confirm that a preview appears, all files are initially selected, files can be selected individually or by group, and the diff button opens a comparison. Apply the Pull and verify the files appear locally.
4. Edit and save a local .gs or .html file. Confirm that saving does not upload it automatically and that Push appears after refreshing the change status.
5. Select Push, review the preview, optionally deselect a file, and apply it. Verify the selected changes in the Apps Script editor.
6. Modify a file in the Apps Script editor, then refresh the extension status. Confirm that Pull appears and its preview shows the remote change.
7. To test conflict detection, first complete a synchronization, then modify the same file locally and remotely before synchronizing again. Refresh the status and confirm that the conflict banner and both actions are shown.
8. Open a .gs file and confirm IntelliSense for services such as SpreadsheetApp is already available without running a setup command.

To test from source instead, run npm ci, then npm test, and press F5 in VS Code to open an Extension Development Host. See INSTALL.md for maintainer and packaging instructions.

Push local changes

Use Push when the panel reports local changes. The preview lists files that will be added, modified, or removed remotely. Everything is selected initially; clear any item you do not want to apply. If the project changes after the preview, the operation is rejected and you must review a fresh preview.

Pull remote changes

Use Pull when the panel reports remote changes. A full Pull also removes valid local Apps Script files that were deleted remotely. Deselected files remain untouched and do not become part of the synchronization baseline.

Conflicts

A conflict means both local and remote versions changed after the last common snapshot, or there is no reliable baseline yet. Review both previews and use the per-file diff button before choosing which direction to apply. The extension does not silently choose a winner.

Automatic autocomplete

Autocomplete for SpreadsheetApp, DriveApp, Logger, and other Apps Script services is enabled by default in trusted GAS workspaces. When a connected project or a workspace containing .gs files is opened, the extension copies its bundled type definitions into a hidden .gas-sync folder and conservatively creates or updates jsconfig.json. It never runs npm and does not create node_modules or modify package.json.

The operation is idempotent and refreshes the local typings only when their packaged version changes or the managed configuration is missing. It can be disabled globally with Google Apps Script Sync › Autocomplete: Enabled in Settings. To exclude only the current project and revert its recorded setup, run Google Apps Script Sync: Undo Apps Script autocomplete setup. Run Set up Apps Script autocomplete to repair or re-enable that project later.

Command Palette

• Sign in with Google / Sign out
• Connect project (by ID)
• Push project (review changes)
• Pull project (review changes)
• Show sync status
• Set up Apps Script autocomplete (repair or re-enable)
• Undo Apps Script autocomplete setup (exclude this project)

Troubleshooting

• Enable the Apps Script API at script.google.com/home/usersettings.
• Confirm that the Script ID is correct and that your Google account can edit the project.
• If a preview expires or the project changes, generate it again.
• If autocomplete is missing, confirm the workspace is trusted and Google Apps Script Sync › Autocomplete: Enabled is on, then reload the window or run the repair command.

Privacy

The extension communicates with Google OAuth, Google user info, and the Apps Script API only for sign-in and requested sync operations. It does not transmit project code to unrelated services and does not log remote source content.

License

MIT — see LICENSE.