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 Tool
• More Help
• Contributing

Example Usage

Here's how to sync a file to use dev1home on device1 and dev2home on device2.

.bashrc on device1:

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

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

Sync the files using your preferred method of choice to device2 then restore. Lines with tags for other devices get automatically commented out.

[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 pip install filetailor. Setup by running filetailor init and following the instructions.

First install with pip and then generate the config file, filetailor.ini, to define where the synced files and YAML are to be saved.

$ pip install filetailor

$ filetailor init
Create "/home/username/.config/filetailor/filetailor.ini"? [Y/n] y

Created "/home/username/.config/filetailor/filetailor.ini".
Update "filetailor.ini" with your desired locations for synced files and configuration YAML, then run "filetailor init" again to create the directories.

$ filetailor init
Reading settings from "filetailor.ini"...
Creating filetailor directories...

Create "/home/username/.local/share/filetailor/sync" as sync_dir folder? [Y/n] y
Created "/home/username/.local/share/filetailor/sync".

Create "/home/username/.local/share/filetailor/yaml" as yaml_dir folder? [Y/n] y
Created "/home/username/.local/share/filetailor/yaml" and default "filetailor.yaml".

Create "/home/username/.cache/filetailor" as staging_dir folder? [Y/n] y
Created "/home/username/.cache/filetailor".

filetailor initialization complete.

See Alternative Installs for other installation methods.

Configuration

filetailor.yaml controls which files sync to which devices.

You can add/remove files to the YAML by running filetailor add PATHS and filetailor remove PATHS. Alternatively, you can update filetailor.yaml manually by following the comments within filetailor.yaml.

The YAML also defines variables, which are strings to replace when restoring to a specific device. An example of a variable would be a path to a file that differs between devices. See the FAQ in the wiki for examples.

Usage

To backup files from the local device to the sync folder, run filetailor backup.

To restore files from the sync folder to the local device, run filetailor restore.

To list all available arguments, run filetailor --help or for command details 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. The line will be commented out on all devices except those listed within the tag. 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 Tool

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

[TOOLS]
diff_tool = YOUR_FAVORITE_DIFF_TOOL

If diff_tool is not set, filetailor uses the first defined diff tool in the following list:

• diff.tool (from Git config, git-difftool docs)
• merge.tool (from Git config, git-mergetool docs)
• core.pager (from Git config, git-config docs)
• diff

One popular diff tool 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