filetailor 0.2.0

Copy and modify plain text files to a folder based on YAML to be synced between devices

filetailor

filetailor is a peer-based configuration management utility for plain-text files (and directories) such as dotfiles. Files are backed up to a specified folder using filetailor, transferred to another device using tools such as Nextcloud, Syncthing, or Git, and then restored on other devices using filetailor again.

During the backup and restore process, filetailor can modify the file contents and path for the specific device according to variables and line-specific controls defined in YAML. See list of features.

Table of Contents generated with DocToc

• Example Usage
• Getting Started
  • Installation
  • Configuration
  • Usage
• Line-Specific Control
  • Example: single-line control
• Diff Programs
• More Help
• Contributing

Example Usage

Here's how to sync a file to use dev1home on "device1" and dev2home on "device2" for the alias MYHOME.

.bashrc on "device1":

alias MYHOME='/home/dev1home/' #{filetailor device1}
# alias MYHOME='/home/dev2home/' #{filetailor device2}

[user@device1 ~]$ filetailor add .bashrc
[user@device1 ~]$ filetailor backup

During backup from "device1" to the sync folder, the first line gets commented out because the tag matches the device name. Sync the sync folder with the backed-up version of the file using your preferred method of choice to "device2" then restore with filetailor. During restore on "device2", the second line gets uncommented (again, because the tag matches the device name).

[user@device2 ~]$ filetailor restore

.bashrc on "device2":

# alias MYHOME='/home/dev1home/' #{filetailor device1}
alias MYHOME='/home/dev2home/' #{filetailor device2}

Getting Started

Installation

filetailor requires Python 3.6+ and pip. Install by running the following commands:

$ pip install filetailor

$ filetailor init
# Update the newly created "filetailor.ini" with your desired locations for synced files and configuration YAML

$ filetailor init
# Accept confirmations to create directories

See Alternative Installs for other installation methods.

Configuration

filetailor.yaml ("the YAML") controls which files sync to which devices.

You can add/remove files to and from the YAML by running filetailor add PATHS and filetailor remove PATHS (local paths are okay). Alternatively, you can update the YAML manually by following the comments within.

The YAML also defines variables, which are strings to replace when restoring to a specific device, such as a path to a file that differs between devices. See the FAQ in the wiki for examples.

Usage

To backup all files defined in the YAML from the local device to the sync folder, run filetailor backup. Lines/blocks matching the device name will be commented out as they are copied to the sync folder.

To restore all files defined in the YAML from the sync folder to the local device, run filetailor restore. Lines/blocks matching the device name will be uncommented as they are copied to the local device.

To list all available commands, run filetailor --help. For command details, run filetailor COMMAND --help.

Line-Specific Control

You can control the contents of individual files by device with line-specific controls such as the Example Usage above. There are two types of line-specific controls: single-line and multi-line.

To use a single-line control, append a tag to the line you want to be commented out on other devices. During backup, any lines tagged for the current device will be commented out. During restore, lines tagged for the current device will be uncommented. Single-line control tag format:

(Code being controlled) COMMENT_SYM{filetailor DEVICES...}

COMMENT_SYM is any symbol(s) used for comments and must be preceded by at least one space.

To control a block of lines, see Multi-line Controls.

Example: single-line control

How the code should be written on "desktop1":

export $device_type="desktop" #{filetailor desktop}
# export $device_type="laptop" #{filetailor laptop1 laptop2}

After backing up the file through filetailor and then restoring to "laptop1" or "laptop2", the code would appear like this:

# export $device_type="desktop" #{filetailor desktop}
export $device_type="laptop" #{filetailor laptop1 laptop2}

How the code would look on any other device and in the filetailor sync folder:

# export $device_type="desktop" #{filetailor desktop}
# export $device_type="laptop" #{filetailor laptop1 laptop2}

Diff Programs

Before backing up or restoring files, filetailor will show a diff of the changes. To set the diff programs for filetailor, add the following option to filetailor.ini.

[TOOLS]
diff_pager = YOUR_FAVORITE_DIFF_PROGRAM  # for viewing diff in terminal
difftool = YOUR_FAVORITE_DIFFTOOL  # for making edits during diff in external tool

If diff_pager is not set, filetailor will use core.pager (from Git config, git-config docs) if defined, otherwise uses diff. If difftool is not set, filetailor will use diff.tool (from Git config, git-difftool docs) if defined, otherwise uses diff.

One popular supported diff pager is Delta. To install, follow the installation instructions in the link.

Run the following command to set Delta as your default pager for Git (and thus filetailor):

$ git config --global core.pager delta

More Help

See FAQ in the wiki for more help and examples.

Links:

• GitHub
• PyPI
• AlternativeTo

Contributing

Feedback is welcome! Ways to contribute include:

• Report a bug
• Recommendations on new features
• Suggestions to improve documentation and print statement readability

Pull requests are welcome as well, but please open an issue first describing the change. When submitting PRs, please try to conform to the following style guides:

• Python code style: PEP8
• Man page formatting: man-pages(7)
• Commit message formatting: How to Write a Git Commit Message
• Packaging: Python Packaging User Guide
• Release versioning: Semantic Versioning