Run from pyftpsync.yaml

Users can define sets of command line options as named tasks and store them in the project folder. It can then be executed like so:

$ pyftpsync run TASK

File Discovery

The file must be named pyftpsync.yaml and located in the root folder of the project.
When pyftpsync run is called, it looks for that file in the current working directory and its parent folders.

When pyftpsync run was called from a subdirectory of the project, it has to be clarified if the synchronization should be done for the whole project (i.e. the root folder where pyftpsync.yaml is located), or only for the current sub branch. This can be done by passing the --root or --here option.

File Format

pyftpsync.yaml defines a list of tasks that have a name and a set of options.
Options are named like the command line arguments, using YAML syntax.

Main sections are

default_task: TASK_NAME (str)

Name of a task that is run when not explicitly specified, i.e. running like pyftpsync run.

common_config (dict)

Contains settings that are shared/inherited by all concrete task definitions.
Same syntax as described in tasks.TASK_NAME.

tasks (dict)

contains one dict per task name

tasks.TASK_NAME (dict)

Contains optins that are passed to the CLI command.

Values are inherited from the common_config section, but can be overridden here.

Typical values include:

command: COMMAND_NAME (str, mandatory)

Command that should be run with the defined options. Must be one of ‘upload’, ‘dowlnload’, ‘sync’, ‘tree’.

remote: URL (str, mandatory)

Remote target URL and protocol, e.g. sftp://example.com/my_project.

local: REL_PATH (str, default: . or current folder)

Local target path, relative to the location of the yaml file.
See also root option.

dry_run: FLAG (bool, default: false)

If true, the task will run in dry-run mode.
A caller can override dry_run: true by passing --execute (or --no-dry-run).
A caller can override dry_run: false by passing --dry-run (or -n).

root: FLAG (bool, default: undefined)

When pyftpsync run was called from a subdirectory, it has to be clarified if the synchronization should be done for the whole project (i.e. the root folder where pyftpsync.yaml is located), or only for the current sub branch.
When here is set, the remote target URL is adjusted relative to the depth.|br| When neither root: true nor here: true are set, the command will prompt the user.

here: FLAG (str, default: undefined)

See root option.

<any> (str, optional)

Most availble command line options can also be added, hovever leading -- must be removed and - replaced with _.
For example --force becomes force: true and --delete-unmatched becomes delete_unmatched: true.

File Execution

A task is started like pyftpsync run TASK, where TASK must be an existing entry in the yaml file.
When pyftpsync run is called without a TASK, it defaults to the task name defined in default_task: TASK.

Task settings can be overidden by command line args, for example:

$ pyftpsync run deploy --execute --force -v

would overide task definition entries in the yaml file: dry_run: false, verbose: 4, and force: true.

Note

If the credentials are already stored in the keyring or .netrc file, a simple pyftpsync run should synchronize the current project without further prompting.
When SFTP is used, also make sure that the remote host’s public key is stored in ~/.ssh/known_hosts.

Example:

 1# Configuration for `pyftpsync run ...` command line tool.
 2# Edit this file, rename to `pyftpsync.yaml`, and store in the project's root folder.
 3# See https://pyftpsync.readthedocs.io/ for details.
 4
 5#: This task is used by `pyftpsync run` if no task name is passed as argument
 6default_task: deploy
 7
 8#: Default settings inherited by all tasks
 9common_config:
10    #: Verbosity (default: 3, use -v/-q to modify from CLI)
11    # verbose: 4
12    #: Show progress
13    progress: true
14    #: Optional relative path to the yaml root (default: .)
15    # local: sync_root
16    #: Remote target protocol and address
17    remote: sftp://example.com/my_project
18    #: Make --dry-run default (pass  `--execute` or `--no-dry-run` to override)
19    dry_run: true
20    #: Make --root default (pass `--here` to override)
21    root: true
22    #: Return exit code 10 on skipped files
23    report_problems: true
24
25#: List of task definitions (inherits settings from `common_config`)
26tasks:
27    show: 
28        command: tree
29        dry_run: false
30        sort: true
31        files: false  # Pass `--files` to override
32
33    sync_all:
34        command: sync
35
36    deploy:
37        command: upload
38        delete: false
39        delete_unmatched: false
40        exclude: build,node_modules,.*,_*
41
42    deploy_force:
43        command: upload
44        # create_folder: true
45        delete: true
46        delete_unmatched: true
47        exclude: build,node_modules,.*,_*
48        force: true
49        resolve: local

For a start, copy Annotated Sample Configuration, rename it to pyftpsync.yaml, and edit it to your needs.