Metadata-Version: 2.1
Name: filetailor
Version: 0.1.0
Summary: Copy and modify plain text files to a folder based on YAML to be synced between devices
Home-page: https://github.com/k4j8/filetailor
Author: Kyle Johnston
Author-email: johnstonkylew@gmail.com
License: UNKNOWN
Project-URL: Bug Tracker, https://github.com/k4j8/filetailor/issues
Platform: UNKNOWN
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE.txt
Requires-Dist: appdirs (>=1.4.4)
Requires-Dist: pyyaml (>=5.4.1)
Requires-Dist: ruamel.yaml (>=0.17.7)
Requires-Dist: termcolor (>=1.1.0)

# 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](https://nextcloud.com/) or [Syncthing](https://syncthing.net/), 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](https://github.com/k4j8/filetailor/wiki/Features).

![flowchart](docs/flowchart.png)

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [filetailor](#filetailor)
  - [Example Usage](#example-usage)
  - [Getting Started](#getting-started)
    - [Installation](#installation)
    - [Configuration](#configuration)
    - [Usage](#usage)
  - [Line-Specific Control](#line-specific-control)
      - [Example: single-line control](#example-single-line-control)
  - [Diff tool](#diff-tool)
  - [Contributing](#contributing)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Example Usage

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

**.bashrc** on `device1`:

```bash
alias MYHOME='/home/dev1home/' #{filetailor device1}
# alias MYHOME='/home/dev2home/' #{filetailor device2}
```
```bash
[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.
```bash
[user@device2 ~]$ filetailor restore
```

**.bashrc** on `device2:`

```bash
# 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.
```bash
$ 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](https://github.com/k4j8/filetailor/wiki/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](https://github.com/k4j8/filetailor/wiki/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](https://github.com/k4j8/filetailor#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:
<pre><code class="text">(Code being controlled) <i>COMMENT_SYM</i><b>{filetailor</b> <i>DEVICES</i>...<b>}</b></code></pre>
`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](https://github.com/k4j8/filetailor/wiki/Multi-Line-Controls).

#### Example: single-line control

How the code should be written on `desktop1`:
```bash
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:
```bash
# 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:
```bash
# 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`.
```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](https://git-scm.com/docs/git-difftool))
- `merge.tool` (from Git config, [git-mergetool docs](https://git-scm.com/docs/git-mergetool))
- `core.pager` (from Git config, [git-config docs](https://git-scm.com/docs/git-config))
- `diff`

One popular diff tool is [Delta](https://github.com/dandavison/delta#installation). To install, follow the installation instructions in the link.

Run the following command to set Delta as your [default pager for Git](https://www.git-scm.com/book/en/v2/Customizing-Git-Git-Configuration) (and thus filetailor):
```bash
$ git config --global core.pager delta
```

## More Help

See [FAQ](https://github.com/k4j8/filetailor/wiki/FAQ) in the wiki for more help and examples.

## 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](https://www.python.org/dev/peps/pep-0008/)
- Man page formatting: [man-pages(7)](https://man7.org/linux/man-pages/man7/man-pages.7.html)
- Commit message formatting: [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- Packaging: [Python Packaging User Guide](https://packaging.python.org/)
- Release versioning: [Semantic Versioning](https://semver.org/)


