preparing for da public

2026-08-31 07:58:12 -07:00
parent 62c475c03e
commit 2cfe265109
3 changed files with 563 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,111 @@
+# ff-logo
+
+Pick a custom image logo for [fastfetch](https://github.com/fastfetch-cli/fastfetch) interactively, using fzf.
+
+## Requirements
+
+| Tool | Purpose |
+|------|---------|
+| `fastfetch` | System info display (must be built with image support) |
+| `fzf` | Interactive selection |
+| `imagemagick` | Image dimension detection (`identify`) |
+| `chafa` or kitty terminal | Image rendering |
+
+ff-logo will detect missing dependencies and offer to install them automatically.
+
+## Platform support
+
+- macOS (Homebrew)
+- Arch Linux / CachyOS (pacman)
+- Debian / Ubuntu (apt)
+
+## Quick start
+
+```sh
+git clone https://github.com/youruser/ff-logo.git
+cd ff-logo
+./ff-logo
+```
+
+On first run, ff-logo checks that fastfetch is installed and has image support. If not, it offers to run `bootstrap-fastfetch.sh` for you.
+
+### Install to PATH
+
+```sh
+./ff-logo --install
+```
+
+Choose between `~/.local/bin` (no sudo), `/usr/local/bin`, or `/usr/bin`.
+
+## fastfetch image support
+
+Most distro packages of fastfetch are compiled without chafa/ImageMagick support. If ff-logo warns you about this, build fastfetch from source with:
+
+```sh
+./bootstrap-fastfetch.sh
+```
+
+This installs build dependencies, compiles fastfetch, and places the binary at `/usr/local/bin/fastfetch`. On macOS it also symlinks the brew-installed chafa and ImageMagick libraries so fastfetch can find them at runtime.
+
+> **CachyOS / Arch users:** the `fastfetch` package from the repos usually lacks image support. Run `bootstrap-fastfetch.sh` once.
+
+## Image directory
+
+ff-logo looks for images in this order:
+
+1. `LOGO_DIR` set in `~/.ff-logo` (config file)
+2. `~/.local/share/fastfetch-images` (XDG local dir)
+3. `~/Pictures`
+
+PNG, JPG, and JPEG files are supported.
+
+## Configuration
+
+```sh
+ff-logo -e          # create/open ~/.ff-logo in $EDITOR
+```
+
+Config file (`~/.ff-logo`) is a sourced bash file:
+
+```bash
+# Directory containing logo images
+LOGO_DIR="$HOME/Pictures/fastfetch-logos"
+
+# Maximum logo size in terminal columns/rows
+MAX_W=83
+MAX_H=44
+
+# Skip the renderer prompt (chafa or kitty)
+DEFAULT_RENDERER=chafa
+```
+
+If no config exists, ff-logo will offer to create one on first run.
+
+## Usage
+
+```
+ff-logo [options]
+
+Options:
+  -e, --edit     Create/edit ~/.ff-logo in $EDITOR
+  --install      Install ff-logo to a bin directory
+  -h, --help     Show help
+```
+
+Running `ff-logo` with no arguments:
+
+1. Checks dependencies (offers to install missing ones)
+2. Verifies fastfetch has image support (offers to run bootstrap if not)
+3. Shows an fzf picker of images in your logo directory
+4. Prompts for a renderer (`chafa` or `kitty`) unless `DEFAULT_RENDERER` is set
+5. Writes the selection to `~/.config/fastfetch/logo-local` and runs fastfetch
+
+## Integrating with fastfetch
+
+Add something like this to your fastfetch config or shell profile to use the saved logo:
+
+```bash
+# ~/.config/fastfetch/config.jsonc  (logo-local is written by ff-logo)
+```
+
+Or call fastfetch directly referencing `logo-local` — see the fastfetch docs for config options.