pole-utils

Utility scripts for Salesforce deployment and retrieval operations.

Installation

npm install -g pole-utils

Or install locally in your project:

npm install pole-utils

Commands

pole-deploy - Deploy Delta Changes

Deploys only the changed files between commits or branches to a Salesforce org. Note: Will NOT deploy deleted files.

Usage

npx pole-deploy --diff <commit|branch> --target <org-alias> [options]

Options

• --diff (required) - The commit hash or branch to compare against
• --target (optional) - The alias for the target org (defaults to the default org)
• --deployinclude (optional) - Include files from .deployinclude file
• --dry-run (optional) - Perform a dry run without actually deploying
• --testlevel (optional) - Test level for deployment (default: NoTestRun)
• --json (optional) - Output results in JSON format

Examples

# Deploy changes between current branch and develop
npx pole-deploy --diff develop --target dev

# Deploy changes from a specific commit
npx pole-deploy --diff b48a0e8402039fd9e76c43601d0f9ade459f2474 --target dev

# Deploy changes with additional files from .deployinclude
npx pole-deploy --diff "master master~3" --target dev --deployinclude

# Dry run deployment
npx pole-deploy --diff develop --target dev --dry-run

pole-retrieve - Retrieve Recent Changes

Retrieves metadata that has been modified in a Salesforce org within a specified time period.

Usage

npx pole-retrieve --target <org-alias> [options]

Options

• --target (optional) - The alias for the target org (defaults to the default org)
• --days (optional) - Number of days to look back for changes (default: 1)
• --only-my-changes (optional) - Filter to only retrieve changes made by the currently authenticated user
• --json (optional) - Output results in JSON format

Examples

# Retrieve changes from the last day
npx pole-retrieve --target dev

# Retrieve changes from the default org the last 100 days
npx pole-retrieve --days 100

# Retrieve only your changes from the last 7 days
npx pole-retrieve --days 7 --only-my-changes

Fork Git Client Integration

If you use Fork Git Client, you can install custom commands for easy access to these utilities.

After installing pole-utils locally in your project, run the following command to copy the custom commands configuration to Fork:

npm explore pole-utils -- npm run fork:copy-commands

This will copy the custom commands configuration to Fork, giving you GUI buttons to:

• Deploy files in a branch
• Deploy files in a commit
• Deploy a selected file
• Retrieve recent changes from an org

If installed globally, the custom commands will be found by running:

which npm

E.g: /opt/homebrew/bin/npm Custom-commands.json is found in the /opt/homebrew/lib/node_modules/pole-utils/fork/ directory.

Requirements

• Node.js
• Git (for pole-deploy command)

How It Works

pole-deploy

1. Uses git diff to identify changed files
2. Filters for Salesforce metadata in force-app/ directory
3. Optionally includes additional files from .deployinclude
4. Deploys only the changed files using Salesforce CLI

pole-retrieve

1. Optionally gets the current user's ID (when --only-my-changes is used)
2. Queries the target org for recent changes to:
   • Permission Sets
   • FlexiPages
   • Other metadata types via SourceMember
3. Retrieves the identified metadata using Salesforce CLI

License

ISC