Configuration

The configuration of Fabsetup is based on the same mechanics as used in Fabric and Invoke.

The configuration file paths are named fabsetup.* instead of fabric.* or invoke.*, for example ~/.fabsetup.yaml instead of ~/.fabric.yaml or ~/.invoke.yaml.

The prefix for environment variables is FABSETUP_, see here for the rules.

See here for the order in which configuration values override one another. To verify which configuration values are currently effective run: fabsetup --show-config. This prints out the merged configuration before task execution.

Values

In addition to the configuration values provided by Fabric and Invoke, Fabsetup comes with the following configurations:

  • outfile: Configure if and how an outfile will be created.

    • name: Path of the outfile where the markdown output will be (over-) written to. If the value is empty on task execution, no outfile will be created. Empty string as default.

    • dir: If non-empty and outfile.name is empty set the value of outfile.name to f"{outfile.dir}/{basename}" before task execution. basename is the formatted outfile.basename_formatter. Empty string as default.

    • basename_formatter: Create a variable filename, by default containing the date and time of execution, the names of the exectued tasks and the name of the hosts (if any was given by -H), each part prepended by an underscore. The default value results in a filename like 'fabsetup_2021-02-21_12:30:45_task1_task2_host1_host2.md' for example. Default value is 'fabsetup_{now}{tasks}{hosts}.md'.

    • now_format: the now variable in outfile.basename_formatter is set with the current date: now = datetime.datetime.now().strftime(now_format). Default value is '%F_%H-%M-%S'.

    • keep_color: When True do not remove ANSI color codes from the markdown outfile. Default value is False.

    • pandoc: Configure file modifications and conversions applied by pandoc.

      • command: Pandoc executable, could be set for example to 'pandoc' or '/usr/bin/pandoc'. Default value is 'pandoc'.

      • toc: If True add a table of contents to the markdown outfile. Default value is False.

      • html: Configure HTML file creation.

        • name: If non-empty on task execution and a markdown outfile exists use pandoc to convert the markdown to an HTML file. Empty string as default.

        • dir: If non-empty and outfile.pandoc.html.name is empty set outfile.pandoc.html.name to f"{dir}/{basename}.html" before task execution. basename is the basename of the markdown outfile without the trailing .md. Empty string as default.

        • css: Configure Cascading Style Sheets.

          • disabled: If True the created HTML file will not use CSS. Default value is False.

          • inline: If True embed the CSS inline into the HTML file, else create a CSS file next to it. Default value is True.

          • url: Empty string as default.

          • auto_remove_markdown_file: Default value is True.

    • prepend_executed_fabsetup_command: Default value is True.

    • fabsetup_command_prefix: Default value is '*Executed fabsetup command:*\n\n'.

    • command_output_prefix: Default value is '(stdout) '.

    • command_errput_prefix: Default value is '(STDERR) '.

  • output: Configure the produced output on fabsetup task execution.

    • color: color configuration

      • cmd_local: Default value is 'green'.

      • cmd_remote: Default value is 'yellow'.

      • docstring: Default value is 'blue'.

      • error: Default value is 'red'.

      • full_name: Default value is 'no_color'.

      • subtask_heading: Default value is 'cyan'.

      • task_heading: Default value is 'magenta'.

    • color_off: Default value is False.

    • hide_command_line: Default value is False.

    • hide_code_block: Default value is False.

    • hide_docstring: Default value is False.

    • hide_heading: Default value is False.

    • hide_print: Default value is False.

    • numbered: Default value is True.

    • numbered_state: Default value is '0'.

    • task_depth: Default value is 1.

  • run: run configuration

    • interactive: Default value is False.

  • load_invoke_tasks_file: Default value is False.

  • load_fabric_fabfile: Default value is False.

  • run_before: Command hook to be executed before fabsetup execution. Empty string as default.

  • run_finally: Command hook to be executed after fabsetup execution. Empty string as default.

Defaults

Fabsetup uses sane defaults and is usable “out of the box”:

{
    "outfile": {
        "name": "",
        "dir": "",
        "basename_formatter": "fabsetup_{now}{tasks}{hosts}.md",
        "now_format": "%F_%H-%M-%S",
        "keep_color": False,
        "pandoc": {
            "command": "pandoc",
            "toc": False,
            "html": {
                "name": "",
                "dir": "",
                "css": {
                    "disabled": False,
                    "inline": True,
                    "url": "",
                    "auto_remove_markdown_file": True,
                },
            },
        },
        "prepend_executed_fabsetup_command": True,
        "fabsetup_command_prefix": "*Executed fabsetup command:*\n\n",
        "command_output_prefix": "(stdout) ",
        "command_errput_prefix": "(STDERR) ",
    },
    "output": {
        "color": {
            "cmd_local": "green",
            "cmd_remote": "yellow",
            "docstring": "blue",
            "error": "red",
            "full_name": "no_color",
            "subtask_heading": "cyan",
            "task_heading": "magenta",
        },
        "color_off": False,
        "hide_command_line": False,
        "hide_code_block": False,
        "hide_docstring": False,
        "hide_heading": False,
        "hide_print": False,
        "numbered": True,
        "numbered_state": "0",
        "task_depth": 1,
    },
    "run": {"interactive": False},
    "load_invoke_tasks_file": False,
    "load_fabric_fabfile": False,
    "run_before": "",
    "run_finally": "",
}

Customization Examples

  • Log every fabsetup call as an HTML file with a table of contents and with inline CSS. Add to Your ~/.fabsetup.yaml:

    outfile:
  dir: ~/.fabsetup-runs
  pandoc:
    html:
      dir: ~/.fabsetup-runs/html
    toc: true

  • Depending on the executed tasks, Fabsetup calls could need some time to finish or ask for interaction. It would be useful if Fabsetup talks to You when such an event occurs. Among others the tool spd-say synthesises speech from text. In order to be informed on this events amend Your ~/.fabsetup.yaml by something like this values:

    run-before: spd-say Yo!
run-on-question: spd-say "Ok Carbon unit: Question!"
run-after: spd-say Done!