Skip to content

hardis:work:save

Description

Command Behavior

Guides the user through the process of saving their work, preparing it for a Merge Request (also named Pull Request), and pushing changes to the remote Git repository.

This command automates several critical steps involved in finalizing a development User Story and integrating it into the main codebase. It ensures that your local changes are properly synchronized, cleaned, and committed before being pushed.

Key functionalities include:

  • Git Status Management: Ensures a clean Git working directory by handling ongoing merges and unstaging files.
  • Org Synchronization (Optional): In interactive mode, prompts the user to pull the latest metadata updates from their scratch org or source-tracked sandbox, ensuring local files reflect the org's state.
  • Package.xml Updates: Automatically generates package.xml and destructiveChanges.xml files based on the Git delta between your current branch and the target branch, reflecting added, modified, and deleted metadata.
  • Automated Source Cleaning: Applies predefined cleaning operations to your local Salesforce sources, such as removing unwanted references, minimizing profiles, or cleaning XML files based on configurations in your .sfdx-hardis.yml.
    • autoCleanTypes: A list of automated source cleanings, configurable via hardis:project:clean:references.
    • autoRemoveUserPermissions: A list of user permissions to automatically remove from profile metadata.
    • The flowPositions cleaning is restricted to the Flows of the git delta package.xml, so it is not run at all when the User Story contains no Flow.
  • Deployment Plan Generation: Builds an automated deployment plan based on the updated package.xml and configured deployment splits.
  • Commit and Push: Guides the user to commit the changes and push them to the remote Git repository, optionally handling force pushes if a branch reset occurred.
  • Merge Request Guidance: Provides information and links to facilitate the creation of a merge request after the changes are pushed.
  • Agent Mode (--agent): Enables a fully non-interactive execution path for AI agents and automation. In this mode, prompts are disabled and decisions are derived from flags and configuration.
  • Expert Mode (SFDX_HARDIS_EXPERT_MODE): Skips the confirmation questions for experienced users, while keeping the prompts that ask for a real choice, like the target branch when it can not be guessed.

Agent Mode Invocation

Use --agent to disable prompts. Typical usage:

sf hardis:work:save --agent

In --agent mode:

  • target branch is resolved from --targetbranch when provided
  • otherwise target branch is inferred from localStorageBranchTargets in user config for the current local branch
  • metadata pull is always skipped (commits are assumed to be already prepared)
  • data export is always skipped
  • push is always attempted at the end of the command (unless --nogit is set)

If target branch cannot be resolved, the command fails fast with a validation error listing available options.

Expert Mode

Set the environment variable SFDX_HARDIS_EXPERT_MODE=true to skip the confirmation questions.

In expert mode:

  • the "have you already committed the updated metadata" question is skipped: your commits are assumed to be ready
  • the data export questions are skipped
  • the cleaning types selection is skipped: only the cleanings listed in autoCleanTypes are applied, none if the property is not set
  • the branch is always pushed to the remote, without confirmation
  • the Merge Request page is opened in your browser at the end of the command

Prompts that ask for a real choice are kept, like the target branch selection when it can not be guessed.

VS Code users can activate it permanently with the setting VsCode SFDX Hardis > User Mode Expert, which sends SFDX_HARDIS_EXPERT_MODE=true to every sfdx-hardis command.

Example .sfdx-hardis.yml configuration:

autoCleanTypes:
  - checkPermissions
  - destructivechanges
  - datadotcom
  - minimizeProfiles
  - listViewsMine
autoRemoveUserPermissions:
  - EnableCommunityAppLauncher
  - FieldServiceAccess
  - OmnichannelInventorySync
  - SendExternalEmailAvailable
  - UseOmnichannelInventoryAPIs
  - ViewDataLeakageEvents
  - ViewMLModels
  - ViewPlatformEvents
  - WorkCalibrationUser

After the push, the org is recorded in the development orgs list of the project with the User Story branch, so its users know when to run a backpromote. Without a git provider token, the command only says it could not record it.

Advanced instructions are available in the Publish a User Story documentation.

Technical explanations

The command's technical implementation involves a series of orchestrated steps:

  • Git Integration: Extensively uses the git utility for status checks, adding files, committing, and pushing. It also leverages sfdx-git-delta for generating metadata differences between Git revisions.
  • Interactive Prompts: Employs the prompts library in interactive mode for decisions like pulling sources or pushing commits. In --agent mode, prompts are skipped.
  • Configuration Management: Reads and updates project and user configurations using getConfig and setConfig to store preferences and deployment plans.
  • Metadata Synchronization: Calls forceSourcePull in interactive mode when requested, and callSfdxGitDelta to generate package.xml and destructiveChanges.xml based on Git changes.
  • XML Manipulation: Utilizes appendPackageXmlFilesContent, removePackageXmlFilesContent, parseXmlFile, and writeXmlFile for modifying package.xml and destructiveChanges.xml files.
  • Automated Cleaning: Integrates with CleanReferences.run and CleanXml.run commands to perform automated cleaning operations on the Salesforce source files.
  • Deployment Plan Building: Dynamically constructs a deployment plan by analyzing the package.xml content and applying configured deployment splits.
  • WebSocket Communication: Uses WebSocketClient.sendRefreshStatusMessage to notify connected VS Code clients about status updates.
  • External Tool Integration: Requires the sfdx-git-delta plugin to be installed for its core functionality.

Learn by doing

The free Salesforce DevOps with sfdx-hardis course runs this command, click by click, on an org of your own, in these labs:

Screenshots

Confirm the metadata is committed before the manifest is updated

Confirm the metadata is committed before the manifest is updated

Push the branch to the git server

Push the branch to the git server

A User Story saved: package.xml updated from the git delta, sources cleaned, commits pushed, ready for a Pull Request

A User Story saved: package.xml updated from the git delta, sources cleaned, commits pushed, ready for a Pull Request

  • (1) The report of the run: the button opens it in Excel, the arrow lists its other files

Reports

The command writes these reports in the hardis-report folder of the project: a CSV file, and its Excel copy (XLSX) in the xls sub-folder.

Package.xml updates

One row per file committed with the package.xml updates, with its status (created, modified or deleted).

Files: commit-files-package-xml-updates-*.csv, xls/commit-files-package-xml-updates-*.xlsx

Package.xml updates report in Excel

Cleaned files

One row per source file cleaned and committed by the save, so the cleaning is visible in the User Story.

Files: commit-files-cleaned-sources-*.csv, xls/commit-files-cleaned-sources-*.xlsx

Cleaned files report in Excel

Deployment plan files

One row per file committed with the deployment plan updates, with its status (created, modified or deleted).

Files: commit-files-deployment-plan-*.csv, xls/commit-files-deployment-plan-*.xlsx

Deployment plan files report in Excel

Parameters

Name Type Description Default Required Options
agent boolean Run in non-interactive mode for agents and automation
auto boolean No user prompts (when called from CI for example)
debug
-d
boolean Activate debug mode (more logs)
flags-dir option Import flag values from a directory.
json boolean Format output as json.
noclean
-c
boolean No cleaning of local sources
nogit
-g
boolean No automated git operations
nopull
-n
boolean No scratch pull before save
skipauth boolean Skip authentication check when a default username is required
target-org
-o
option Username or alias of the target org. Not required if the target-org configuration variable is already set. true
targetbranch option Name of the Merge Request target branch. Will be guessed or prompted if not provided.
websocket option Websocket host:port for VsCode SFDX Hardis UI integration

Examples

$ sf hardis:work:task:save
$ sf hardis:work:task:save --nopull --nogit --noclean
$ sf hardis:work:save --agent --targetbranch integration

Comments