From 6b1ed40f0bbffad4e289a999ae39dec63f414523 Mon Sep 17 00:00:00 2001 From: tomruk <41700170+tomruk@users.noreply.github.com> Date: Sat, 3 Aug 2024 20:34:58 +0300 Subject: [PATCH] Comment out config, and update README --- README.md | 45 +++++++++++++++++++++++++--- kopyat_example.yml | 74 +++++++++++++++++++++++----------------------- 2 files changed, 78 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 1100441..42ccc44 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,28 @@ -# kopyat +# Kopyat -The name kopyat comes from 2 words: kopya (Turkish for "copy") and cat -> copycat. +Kopyat is my Swiss Army knife for backup and sync related tasks. The name Kopyat comes from 2 words: kopya (Turkish for "copy") and cat -> copycat. + +Functionalities: +- Serve as a wrapper for backup programs (for now, only supported backup program is restic), optionally providing ifile support. +- Generate ifile (`.stignore`) for syncthing directories. + +## Ifile + +Ifile is a type of file generated from `.gitignore` and `.kopyatignore` (same format as `.gitignore`) files found inside the directory tree. + +"I" of the ifile stands for both ignore and include. For restic backups, it generates an simple straightforward include file, and for syncthing, it generates an ignore file (`.stignore`). + +## Build + +```shell +git clone https://github.com/karagenc/kopyat +cd kopyat +make +``` ## Config -- Paths in config are relative to the config file. Exception to this are backup base path and backup paths. They must be absolute in order for ifile to be generated without problems. +**Note:** Paths in config are relative to the config file. Exception to this are backup base path and backup paths. They must be absolute in order for ifile to be generated without problems. ### Environment variables @@ -15,14 +33,33 @@ The name kopyat comes from 2 words: kopya (Turkish for "copy") and cat -> copyca ### Hooks (Scripts) +Kopyat can run hooks before or after backup and ifile generation operations. Hooks are simply Go source files with an `init` function. Save the code snippet below as `hello.go`, and run it with: `kopyat run-script hello.go` + ```go package x // ^ package name can be anything, including main. -import "github.com/karagenc/kopyat" +import "fmt" func init() { + fmt.Println("Hello from hook script") +} +``` + +To access context-specific information, import `kopyat` and: +```go +package x +// ^ package name can be anything, including main. + +import "github.com/karagenc/kopyat" + +func init() { + // Get Kopyat context. + // Only for backup and ifile generation hooks. + c := kopyat.GetContext() + // Access context + // ... } ``` diff --git a/kopyat_example.yml b/kopyat_example.yml index 4e48d85..e960e55 100644 --- a/kopyat_example.yml +++ b/kopyat_example.yml @@ -1,13 +1,13 @@ backups: run: - - name: home - restic: - repo: /var/backup/path/to/restic/repo + #- name: home + #restic: + #repo: /var/backup/path/to/restic/repo # If this is set to true, restic command will be prefixed with sudo. # Keep in mind that this is not supported on Windows. - sudo: false + #sudo: false # Extra arguments for restic. $HOSTNAME is defined in `env` section. - extra_args: "-H $HOSTNAME" + #extra_args: "-H $HOSTNAME" # Optional password. If you set this, restic will not ask the password of the # repository. Make sure no untrusted party can access this configuration file # before setting this option. You might want to check permissions of this configuration file. @@ -16,60 +16,60 @@ backups: # Generate and use ifile. # This is the primary functionality of Kopyat. If this is set to true, - # Kopyat will read .gitignore and .kpignore files and generate an ifile + # Kopyat will read .gitignore and .kopyatignore files and generate an ifile # from them. Then your backup program will read that ifile and backup files - # that are not ignored by .gitignore or .kpignore files. If you disable this, + # that are not ignored by .gitignore or .kopyatignore files. If you disable this, # backups will be done as usual. (Backup program will include all files and # directories specified by `paths`.) - use_ifile: true + #use_ifile: true # Hooks (scripts or programs) that are going to run before (pre) and after (post) this backup. - hooks: - pre: - - $HOME/scripts/only-if.go Windows - post: - - '$HOME/scripts/warn-size.go "50 MB"' + #hooks: + #pre: + #- $HOME/scripts/only-if.go Windows + #post: + #- '$HOME/scripts/warn-size.go "50 MB"' # Reminders that are going to be prompted before (pre) and after (post) this backup. - reminders: - pre: - - This is a reminder that is going to be displayed before this backup. - post: - - | - This is a reminder that is going to be displayed after this backup. - In YAML, you can write multiline strings like this. + #reminders: + #pre: + #- This is a reminder that is going to be displayed before this backup. + #post: + #- | + # This is a reminder that is going to be displayed after this backup. + # In YAML, you can write multiline strings like this. # Base directory of this backup. All paths below will be appended (joined) to this. # They will become `/home/glenda/Desktop` and `/home/glenda/Documents`. # You can comment this out if you would not like to use a base directory. - base: $HOME - paths: - - Desktop - - Documents - - .ssh + #base: $HOME + #paths: + #- Desktop + #- Documents + #- .ssh # Files are allowed too: - - .config/user-dirs.dirs + #- .config/user-dirs.dirs ifile_generation: run: - - # Path to .stignore. Its directory and subdirectories will be scanned for files, - # .gitignore's, and .kpignore's to generate this ifile. - ifile: $PHOTOS_PATH/.stignore + #- # Path to .stignore. Its directory and subdirectories will be scanned for files, + # .gitignore's, and .kopyatignore's to generate this ifile. + #ifile: $PHOTOS_PATH/.stignore # What type of ifile are we generating? (For now, only valid option is `syncthing`.) - mode: syncthing + #mode: syncthing # Hooks (scripts or programs) that are going to run before (pre) and after (post) generation of this ifile. - hooks: - pre: - - $HOME/scripts/notify.go Synchronizing $PHOTOS_PATH - post: - - $HOME/scripts/notify.go Synchronization of $PHOTOS_PATH is successful + #hooks: + #pre: + #- $HOME/scripts/notify.go Synchronizing $PHOTOS_PATH + #post: + #- $HOME/scripts/notify.go Synchronization of $PHOTOS_PATH is successful # Environment variables to be set. # Their key will be always be uppercase. If you type their key with # lowercase characters, their key will be converted to uppercase. env: - HOSTNAME: StevesComputer - PHOTOS_PATH: $HOME/photos + #HOSTNAME: StevesComputer + #PHOTOS_PATH: $HOME/photos service: # By default, Kopyat service logs to stdout.