zester
GuidesModules

file.symlink

Ensures a symbolic link exists at a given path pointing to a specified target.

Parameters

ParameterTypeDefaultDescription
namestringstate IDPath where the symlink should be created
targetstring(required)The destination the symlink should point to
forceboolfalseReplace an existing file or wrong-target symlink at name
makedirsboolfalseCreate parent directories if they do not exist

Example

# Create a symlink using the state ID as the link path.
/usr/local/bin/python:
  file.symlink:
    - target: /usr/bin/python3

# Create a symlink with makedirs and force.
/opt/app/config:
  file.symlink:
    - target: /etc/app/config
    - force: true
    - makedirs: true
    - require:
      - "file.directory:/opt/app"

Behavior

PhaseAction
CheckReadlink — returns NeedsChange: true if symlink is absent or points to the wrong target
ApplyRemove existing (if force: true) then Symlink. Creates parent dirs if makedirs: true.
RevertRemove the symlink

Notes

  • If force: false (the default) and a file or symlink already exists at name with a different target, Apply returns an error.
  • makedirs creates the full parent directory path with mode 0755. Use file.directory if you need a specific mode.
  • Revert removes the symlink but does not restore any file that was replaced when force: true was used.

file.append

Ensures specific lines are present in a file, appending any that are missing.

file.recurse

Recursively copies a source directory tree to a destination directory. Mirrors the source structure, creating directories and files with the specified permissions and ownership.

On this page

ParametersExampleBehaviorNotes