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 intasks.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 overridedry_run: true
by passing--execute
(or--no-dry-run
).
A caller can overridedry_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.
Whenhere
is set, the remote target URL is adjusted relative to the depth.|br| When neitherroot: true
norhere: 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
becomesforce: true
and--delete-unmatched
becomesdelete_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.