https://github.com/endlesstrax/kachi
Kachi is a simple tool for backing up valuable files.
https://github.com/endlesstrax/kachi
backup-tool backup-utility dotfiles executable
Last synced: 4 months ago
JSON representation
Kachi is a simple tool for backing up valuable files.
- Host: GitHub
- URL: https://github.com/endlesstrax/kachi
- Owner: EndlessTrax
- Created: 2024-06-05T14:44:33.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-09-02T21:06:23.000Z (10 months ago)
- Last Synced: 2025-09-30T16:45:46.474Z (9 months ago)
- Topics: backup-tool, backup-utility, dotfiles, executable
- Language: Python
- Homepage:
- Size: 129 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
Awesome Lists containing this project
README
# Kachi
Kachi is a simple tool for backing up valuable files, such as dotfiles, config files, and any directory you wish to backup.
By creating a short yaml file, you can declaratively decide what to back up, and where.
Kachi uses "profiles", which allow you to backup different files and directories to different locations, and potentially on different schedules (if you automate it further).
```text
➜ kachi --help
Usage: kachi [OPTIONS] COMMAND [ARGS]...
Kachi is a simple tool for backing up valuable files.
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --version Show current version
│ --install-completion Install completion for the current shell.
│ --show-completion Show completion for the current shell, to copy it or
│ customize the installation.
│ --help Show this message and exit.
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────╮
│ backup Backup files and directories.
╰──────────────────────────────────────────────────────────────────────────────────────╯
```
## Installing
### Quick Install (Linux)
For Linux x64 systems, you can use the installation script to automatically download and install the latest version:
**Option 1: One-liner (requires trust)**
```bash
curl -fsSL https://raw.githubusercontent.com/EndlessTrax/kachi/main/install.sh | bash
```
**Option 2: Inspect before running (recommended)**
```bash
curl -fsSL https://raw.githubusercontent.com/EndlessTrax/kachi/main/install.sh -o install.sh
# Inspect the script
cat install.sh
# Run it if you're satisfied
bash install.sh
```
This will download the latest release for your system and install it to `~/.local/bin/kachi`. Make sure `~/.local/bin` is in your `PATH`.
### Quick Install (Windows)
For Windows x64 systems, you can use the PowerShell installation script to automatically download and install the latest version:
**Option 1: One-liner (requires trust)**
```powershell
irm https://raw.githubusercontent.com/EndlessTrax/kachi/main/install.ps1 | iex
```
**Option 2: Inspect before running (recommended)**
```powershell
irm https://raw.githubusercontent.com/EndlessTrax/kachi/main/install.ps1 -OutFile install.ps1
# Inspect the script
Get-Content install.ps1
# Run it if you're satisfied
.\install.ps1
```
This will download the latest release for your system and install it to `$HOME\.local\bin\kachi.exe`. Make sure `$HOME\.local\bin` is in your `PATH`.
### Manual Installation
Kachi is deployed as a single executable file that you can [download from the releases page](https://github.com/EndlessTrax/kachi/releases). Once downloaded, move it to a location that makes sense for your system and OS, and add it to your PATH.
> NOTE: If a compatible executable for your OS and architecture isn't available, please create an issue or upvote a current one so it can be moved up in priority and added to future releases.
### Verifying Downloads
Each release includes a `checksums.txt` file containing SHA256 checksums for all release artifacts. To verify the integrity of your download:
**On Linux/macOS:**
```bash
sha256sum -c checksums.txt
```
**On Windows (PowerShell):**
```powershell
$hash = (Get-FileHash -Algorithm SHA256 kachi-v*-windows-x64.exe).Hash.ToLower()
$expected = (Get-Content checksums.txt | Select-String "windows-x64.exe").Line.Split()[0]
if ($hash -eq $expected) { Write-Host "Checksum verified!" } else { Write-Host "Checksum mismatch!" }
```
Alternatively, you can manually compare the SHA256 hash of your downloaded file with the corresponding entry in `checksums.txt`.
## Configuration
By default, Kachi looks for a configuration file at `.config/kachi/config.yaml` relative to the user's home directory on all systems. You can specify a different configuration location using the `--config` flag (see usage example below.)
As mentioned above, you can declare different profiles under the top-level `profiles` key. Profiles can be named almost anything you want. The only exception is the `default` profile. While not required, the `default` profile is a handy way of reducing repetition in your configuration file. Any source added to the default profile will be added to all other profiles automatically when backed up.
Example:
```yaml
profiles:
default:
sources:
- ".gitconfig"
backup_destination: "path/to/backup/location/"
profile_1:
sources:
- ".bashrc"
```
> NOTE: A fuller [example of the config.yaml](examples/example.yaml) file can be found in the examples folder.
In the above example, if you backup `profile_1`, both the `.gitconfig` and `.bashrc` files will be backed up to the default `backup_destination`. If a `backup_destination` was declared in `profile_1`, then that would take precedence.
> NOTE: Additional config formats (such as JSON — see [#14](https://github.com/EndlessTrax/kachi/issues/14)) are planned. Please upvote any issues you wish to see prioritized.
## Usage
To back up the declared sources from your configuration, use the `backup` command with optional flags:
```text
➜ kachi backup --help
Usage: kachi backup [OPTIONS]
Backup files and directories.
If no profile is specified, all profiles in the configuration file will be backed up.
If no configuration file is specified, the default configuration file path will be
used.
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --config TEXT Path to a configuration file
│ --profile TEXT Name of the profile to backup
│ --help Show this message and exit.
╰──────────────────────────────────────────────────────────────────────────────────────╯
```
Without any flags, all profiles will be backed up using a config file in the expected default location. Alternatively, specify a single profile to backup with `--profile`:
```bash
kachi backup --profile profile_1
```
Or specify a configuration to use using `--config`:
```bash
kachi backup --config some/other/path/config.yaml
```
## Development
Kachi uses [uv](https://docs.astral.sh/uv/) for package and environment management.
```bash
uv sync --all-extras --dev # install dependencies
uv run pytest # run tests with coverage
uv run ruff check . # lint
uv run ruff format . # format
```
## Contributing
If you find a bug, please file an [issue](https://github.com/EndlessTrax/kachi/issues).
If you have feature requests, please [file an issue](https://github.com/EndlessTrax/kachi/issues) and use the appropriate label.
Please **raise an issue before making a PR**, so that the issue and implementation can be discussed before you write any code. This will save you time, and increase the chances of your PR being merged without significant changes.
Please **include tests** for any PRs that include code (unless current tests already cover your contribution).
Please **lint and format your code** with [ruff](https://github.com/astral-sh/ruff) before submitting.