vim2bat 0.1.0__tar.gz

vim2bat-0.1.0/.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7
+
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7
+
+  - package-ecosystem: "pre-commit"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7

vim2bat-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+
+      - run: uv lock --check
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+      - run: uv run mypy
+
+  test:
+    strategy:
+      matrix:
+        os: [macos-latest, ubuntu-latest]
+        python: ["3.11", "3.12", "3.13", "3.14", "3.15"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install Vim and bat (macOS)
+        if: runner.os == 'macOS'
+        run: brew install vim bat
+
+      - name: Install Vim and bat (Linux)
+        if: runner.os == 'Linux'
+        # Debian and Ubuntu name bat's binary batcat.
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y vim bat
+          sudo ln -s /usr/bin/batcat /usr/local/bin/bat
+
+      - run: uv sync --locked
+      - run: uv run pytest

vim2bat-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,105 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+
+      - name: Check that the tag matches the package version
+        run: |
+          VERSION="$(uv version --short)"
+          if [ "$GITHUB_REF_NAME" != "v$VERSION" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match package version $VERSION"
+            exit 1
+          fi
+
+      - run: uv build
+
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/vim2bat
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" dist/* \
+            --title "$GITHUB_REF_NAME" \
+            --generate-notes
+
+  homebrew:
+    needs: github-release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    env:
+      HOMEBREW_TAP_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Update Homebrew formula
+        # secrets context is not available in `if` expressions, so we check
+        # the job-level env var instead.
+        if: env.HOMEBREW_TAP_TOKEN != ''
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+
+          TARBALL_URL="https://github.com/$GITHUB_REPOSITORY/archive/refs/tags/$GITHUB_REF_NAME.tar.gz"
+          curl -fsSL "$TARBALL_URL" -o /tmp/source.tar.gz
+          SHA=$(sha256sum /tmp/source.tar.gz | awk '{print $1}')
+
+          sed -e "s/VERSION_PLACEHOLDER/$VERSION/g" \
+              -e "s/SHA_PLACEHOLDER/$SHA/g" \
+              formula/vim2bat.rb > /tmp/vim2bat.rb
+
+          git clone "https://x-access-token:${HOMEBREW_TAP_TOKEN}@github.com/redodson01/homebrew-tap.git" /tmp/tap
+          cd /tmp/tap
+          cp /tmp/vim2bat.rb vim2bat.rb
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add vim2bat.rb
+          git diff --cached --quiet || { git commit -m "vim2bat ${VERSION}" && git push; }

vim2bat-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Editors and macOS
+.DS_Store
+*~
+*.swp
+*.swo

vim2bat-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.3
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.13.7
+    hooks:
+      - id: uv-lock

vim2bat-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-05
+
+### Added
+
+- `vim2bat SCHEME` builds bat themes from a Vim colorscheme as Vim shows it with
+  your vimrc: `vim-SCHEME-dark` and `vim-SCHEME-light`, or `vim-SCHEME` for a
+  scheme with one background
+- `--all` builds every colorscheme Vim lists, several at a time
+- `--strict`, `--truecolor`, `--palette 16|256` and `--clean`
+- `vim2bat compare THEME FILE...` measures a theme against Vim
+- Support for Python 3.11 or newer
+- Homebrew install via `brew install redodson01/tap/vim2bat`
+- PyPI package, installed with `uv tool install vim2bat` or
+  `pipx install vim2bat`
+- Source install via `uv tool install .`
+- CI that runs ruff, the format check and mypy, and runs the tests on macOS
+  and Linux for Python 3.11 through 3.15
+- pre-commit hooks for ruff, the uv lockfile and basic file checks
+- Release workflow that, on tag push, checks the tag against the package
+  version, publishes to PyPI through trusted publishing, creates a GitHub
+  release with the built files and updates the redodson01/homebrew-tap formula
+- Dependabot config for keeping GitHub Actions, uv dependencies and pre-commit
+  hooks current
+
+[Unreleased]: https://github.com/redodson01/vim2bat/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/redodson01/vim2bat/releases/tag/v0.1.0

vim2bat-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,137 @@
+# Contributing to vim2bat
+
+## Development
+
+vim2bat is a Python package that uses only the standard library. The code is in
+`src/vim2bat/cli.py`, and `src/vim2bat/share/` holds two Vim scripts and two
+tables. You need Vim, bat and [uv](https://docs.astral.sh/uv/) (`brew install
+uv`). uv uses Python 3.11 or newer and downloads one if none is installed, and
+it installs the dev tools (pytest, mypy, ruff and pre-commit) at the versions in
+`uv.lock`.
+
+```bash
+uv sync                    # creates .venv with an editable install of vim2bat and the dev tools
+uv run pre-commit install  # installs the git hook described below
+uv run pytest              # unit tests, plus integration tests when vim and bat are installed
+uv run mypy                # type checks src and tests in strict mode
+uv run ruff check          # lints (add --fix to apply the safe fixes)
+uv run ruff format         # formats
+```
+
+`uv run` brings `.venv` up to date with `uv.lock` before it runs a command, and
+because the install is editable, changes under `src/` take effect without
+reinstalling.
+
+The pre-commit hook runs on the files you commit. It lints them with
+`ruff check --fix`, formats them with `ruff format`, runs `uv lock` when
+`pyproject.toml` or `uv.lock` changes, trims trailing whitespace, fixes final
+newlines, checks YAML and TOML syntax, and rejects large files. It doesn't run
+mypy or the tests.
+
+The integration tests build themes from the test colorschemes in
+`tests/fixtures/colors`, in a scratch home, bat config and cache, and compare
+the strict themes with the files in `tests/golden`. After an intended change to
+the output, regenerate those files and check their diff:
+
+```bash
+UPDATE_GOLDEN=1 uv run pytest
+```
+
+## Measuring a change
+
+`uv run vim2bat compare THEME FILE...` measures a theme against Vim. Before and
+after a change to the tables, rebuild the theme with `uv run vim2bat SCHEME`,
+which uses your checkout, and measure it on a representative set of your own
+code. Keep those files out of the repository.
+
+## The tables
+
+`src/vim2bat/share/strict.tsv` maps each of Vim's standard groups to the
+TextMate scopes with the same meaning, one row per group: `GROUP<TAB>SCOPES`.
+
+`src/vim2bat/share/loose.tsv` adds language-specific rows:
+`FILETYPE<TAB>GROUP<TAB>SCOPES`. vim-solarized8's language-specific coloring
+decides which languages and tokens are in scope. A new row follows these rules:
+
+1. Map scopes that bat already assigns to the Vim group that Vim gives the same
+   tokens, by meaning.
+2. Use the first group in the token's link chain (as `vim2bat compare` lists
+   it) that exists in Table 1 (the groups vim2bat records from Vim), or
+   `Normal` for tokens that Vim leaves plain. When one scope covers tokens with
+   different chains, use the first group they all share.
+3. The filetype column is the Vim filetype whose syntax file defines the group.
+4. Qualify every selector by language: a language-suffixed scope, or the
+   language's root scope plus exactly one other scope. No selector combines two
+   non-root scopes, and none uses exclusions.
+5. Don't rely on the order of rows with equal specificity.
+6. Stop when every remaining kind of mismatch is under 1% of characters, or
+   would need a rule that depends on context.
+7. Don't fit rows to particular files.
+
+## Pull requests
+
+- Keep PRs focused on a single change
+- Ensure `uv run ruff check`, `uv run ruff format --check`, `uv run mypy` and
+  `uv run pytest` pass (CI runs all four, checks that `uv.lock` is current, and
+  runs the tests on macOS and Linux with Python 3.11 through 3.15)
+- Update `CHANGELOG.md` under `[Unreleased]` when making a notable change
+- Use atomic, logically-ordered commits
+- Follow the commit message style of the existing history
+
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html):
+
+- **MAJOR** for incompatible CLI changes or theme names
+- **MINOR** for backwards-compatible new features
+- **PATCH** for backwards-compatible bug fixes
+
+## Releasing
+
+1. Run `uv version --bump patch` (or `minor` or `major`). It sets the new
+   version in `pyproject.toml` and `uv.lock`, and `vim2bat --version` reads it
+   from the installed package.
+2. In `CHANGELOG.md`, move the `[Unreleased]` entries under a new
+   `## [X.Y.Z] - YYYY-MM-DD` heading, change the `[Unreleased]` link to compare
+   `vX.Y.Z...HEAD`, and add an `[X.Y.Z]` link that compares the previous tag
+   with `vX.Y.Z`.
+3. Commit and push, then push a `vX.Y.Z` tag for the new version.
+
+The release workflow checks that the tag matches the version in
+`pyproject.toml`, builds the sdist and wheel with `uv build`, and publishes them
+to PyPI through trusted publishing. It then creates the GitHub release with the
+built files attached, and updates the formula in
+[redodson01/homebrew-tap](https://github.com/redodson01/homebrew-tap) using the
+`HOMEBREW_TAP_TOKEN` secret. Each job runs only after the one before it
+succeeds, so a tag that doesn't match the version publishes nothing.
+
+### One-time setup
+
+Before the first release:
+
+1. Create redodson01/vim2bat on GitHub as a public repository and push `main`.
+   The tap update downloads the tag's source tarball without credentials, and
+   Dependabot's pre-commit updates work only in public repositories.
+2. On PyPI, add a pending trusted publisher on the GitHub tab of your account's
+   [Publishing](https://pypi.org/manage/account/publishing/) page:
+
+   | Field | Value |
+   |---|---|
+   | PyPI Project Name | `vim2bat` |
+   | Owner | `redodson01` |
+   | Repository name | `vim2bat` |
+   | Workflow name | `release.yml` |
+   | Environment name | `pypi` |
+
+   A pending publisher doesn't reserve the name, and it stops working if
+   someone else registers vim2bat first. The first upload turns it into a
+   normal publisher.
+3. Optionally, create the `pypi` environment on GitHub (Settings, Environments)
+   and add yourself as a required reviewer, so that each PyPI upload waits for
+   your approval. Do this before the first tag, because a release run otherwise
+   creates the environment with no protection rules. On the Free plan, required
+   reviewers work only in public repositories.
+4. Add a repository secret named `HOMEBREW_TAP_TOKEN` (Settings, Secrets and
+   variables, Actions). It holds a fine-grained personal access token limited
+   to redodson01/homebrew-tap, with Contents set to read and write. Without it,
+   the release skips the tap update.

vim2bat-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard E. Dodson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vim2bat-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.5
+Name: vim2bat
+Version: 0.1.0
+Summary: Generate bat themes from Vim colorschemes
+Project-URL: Homepage, https://github.com/redodson01/vim2bat
+Project-URL: Repository, https://github.com/redodson01/vim2bat
+Project-URL: Issues, https://github.com/redodson01/vim2bat/issues
+Project-URL: Changelog, https://github.com/redodson01/vim2bat/blob/main/CHANGELOG.md
+Author: Richard E. Dodson
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Text Editors
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# vim2bat
+
+[![CI](https://github.com/redodson01/vim2bat/actions/workflows/ci.yml/badge.svg)](https://github.com/redodson01/vim2bat/actions/workflows/ci.yml)
+[![Version](https://img.shields.io/github/v/release/redodson01/vim2bat)](https://github.com/redodson01/vim2bat/releases/latest)
+[![Release Date](https://img.shields.io/github/release-date/redodson01/vim2bat)](https://github.com/redodson01/vim2bat/releases/latest)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/redodson01/vim2bat/blob/main/LICENSE)
+
+Builds [bat](https://github.com/sharkdp/bat) themes from Vim colorschemes, so
+that bat, and tools that use it such as fzf.vim's previews and delta, color code
+the way Vim does.
+
+## The problem
+
+bat ships its own themes, and most of them use 24-bit colors. If you use a Vim
+colorscheme, especially one built on your terminal's palette like solarized8
+with `g:solarized_use16`, the previews and diffs that bat colors look different
+from the code you edit in Vim. A matching bat theme means mapping Vim's
+highlight groups to TextMate scopes by hand, for each scheme and background.
+
+vim2bat asks Vim which colors a colorscheme gives each highlight group, with
+your vimrc, and writes bat themes that use the same palette slots, or the same
+24-bit colors.
+
+## Install
+
+### Homebrew (macOS and Linux)
+
+```bash
+brew install redodson01/tap/vim2bat
+```
+
+### PyPI
+
+```bash
+uv tool install vim2bat   # or: pipx install vim2bat
+```
+
+### From source
+
+```bash
+git clone https://github.com/redodson01/vim2bat.git
+cd vim2bat
+uv tool install .   # or: uv tool install --editable . to follow edits to the checkout
+```
+
+The PyPI and source installs put the `vim2bat` command in `~/.local/bin` by
+default. Make sure that folder is on your `$PATH` (`uv tool update-shell` or
+`pipx ensurepath` adds it).
+
+## Runtime requirements
+
+- Vim 9.1 or newer, with the colorschemes you want to convert
+- bat (0.25 or newer for the `--theme-dark` and `--theme-light` settings below)
+- Python 3.11 or newer
+
+Debian and Ubuntu install bat as `batcat`. vim2bat runs `bat`, so link it:
+`ln -s /usr/bin/batcat ~/.local/bin/bat`.
+
+## Usage
+
+```bash
+vim2bat retrobox     # builds vim-retrobox-dark and vim-retrobox-light
+vim2bat --all        # builds every colorscheme Vim lists
+bat --theme=vim-retrobox-dark file.rb
+```
+
+| Option | Effect |
+|---|---|
+| `-a`, `--all` | Builds every colorscheme Vim lists, several at a time |
+| `-c`, `--clean` | First deletes vim2bat's cache and the whole bat themes folder |
+| `-s`, `--strict` | Maps only Vim's standard highlight groups, such as `Comment` and `String` |
+| `-t`, `--truecolor` | Turns on `termguicolors`, so the themes use the scheme's 24-bit colors |
+| `-p`, `--palette 16\|256` | Overrides your vimrc's `t_Co` |
+
+vim2bat rebuilds bat's cache when it finishes, so the themes are available right
+away.
+
+### Theme names
+
+A scheme that supports both backgrounds gets `vim-SCHEME-dark` and
+`vim-SCHEME-light`. A scheme that supports a single background, by setting
+`background` itself, gets `vim-SCHEME`.
+
+### What decides the colors
+
+Vim runs with your vimrc in a 256-color terminal, so your vimrc decides what the
+themes look like: a scheme's own options (such as `g:solarized_use16`), `t_Co`
+and `termguicolors` all apply. `-p` and `-t` override `t_Co` and
+`termguicolors` for one run. Each theme records the options it was built with in
+its `comment` entry. `-p` has no effect while `termguicolors` is on, whether
+from `-t` or your vimrc.
+
+With `-t`, bat prints the exact colors only when `COLORTERM` is `truecolor` or
+`24bit`. Otherwise it rounds them to the nearest of 256.
+
+## Using the themes
+
+### bat
+
+Add these lines to bat's config file, whose path `bat --config-file` prints:
+
+```
+--theme-dark="vim-retrobox-dark"
+--theme-light="vim-retrobox-light"
+--italic-text=always
+```
+
+bat's default, `--theme=auto`, picks between them by asking the terminal for its
+background. It doesn't ask when its output goes to a pipe, as in fzf.vim's
+previews, and then uses its own default theme. On macOS, `--theme="auto:system"`
+follows the system appearance instead, and works in pipes too.
+
+bat leaves out italics unless `--italic-text` is `always`.
+
+### delta
+
+delta takes a single syntax theme:
+
+```ini
+[delta]
+    syntax-theme = vim-retrobox-dark
+```
+
+On macOS, git's pager command can pick the theme from the system appearance:
+
+```ini
+[core]
+    pager = delta --syntax-theme=vim-retrobox-$(defaults read -g AppleInterfaceStyle 2>/dev/null | grep -qx Dark && echo dark || echo light)
+```
+
+## Measuring a theme
+
+`vim2bat compare THEME FILE...` reports how often the theme gives each
+character the color Vim does, per file and per language, then the most common
+mismatches:
+
+```bash
+vim2bat compare vim-retrobox-dark app/models/*.rb
+```
+
+Expect 85 to 90 percent on real code in the languages Table 3 covers (see
+below): bat's syntax definitions don't split code exactly the way Vim's do.
+Other languages get only Table 2 and score lower.
+
+## How it works
+
+1. For each background, vim2bat runs Vim with your vimrc on a pseudo-terminal,
+   loads the scheme, and records each highlight group's colors and attributes
+   (Table 1, cached in `$XDG_CACHE_HOME/vim2bat/tables`, or
+   `~/.cache/vim2bat/tables`). Vim gets a terminal because
+   without one it numbers named colors such as `DarkBlue` differently.
+2. `src/vim2bat/share/strict.tsv` (Table 2) maps Vim's standard groups, such
+   as `Comment` and `String`, to the TextMate scopes with the same meaning.
+3. `src/vim2bat/share/loose.tsv` (Table 3) maps language-specific scopes to the
+   Vim syntax groups that Vim gives the same tokens, for Ruby, ERB, HTML, CSS
+   and SCSS, TypeScript and TSX, JavaScript and JSX, YAML, Vim script, git
+   commit messages and diffs. The languages and tokens follow what
+   vim-solarized8 colors.
+4. Palette colors use bat's palette notation, where `#0E000000` means slot 14,
+   and the terminal's default color is `#00000001`.
+
+## Known limits
+
+- bat doesn't paint a scheme's background color, so a scheme with its own
+  background, such as habamax, sits on your terminal's.
+- bat themes support only bold, italic and underline, so reverse and undercurl
+  are dropped.
+- `-c` deletes the whole bat themes folder, including themes vim2bat didn't
+  build.
+- A single-background scheme whose own name ends in `-dark` or `-light` gets a
+  name that looks like another scheme's background variant.
+- Colorschemes in a subfolder of `colors/`, whose names contain `/`, aren't
+  supported. vim2bat rejects those names.
+
+## Uninstall
+
+```bash
+brew uninstall vim2bat   # or: uv tool uninstall vim2bat, or pipx uninstall vim2bat
+rm "$(bat --config-dir)"/themes/vim-*.tmTheme && (cd / && bat cache --build)
+rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/vim2bat"
+```
+
+## Development
+
+Development uses [uv](https://docs.astral.sh/uv/) (`brew install uv`).
+
+```bash
+git clone https://github.com/redodson01/vim2bat.git
+cd vim2bat
+uv sync                    # creates .venv with vim2bat and the dev tools
+uv run pre-commit install  # runs ruff and file checks before each commit
+uv run pytest              # unit tests, plus integration tests when vim and bat are installed
+uv run mypy                # type checks src and tests
+uv run ruff check          # lints
+uv run ruff format         # formats
+```
+
+[CONTRIBUTING.md](https://github.com/redodson01/vim2bat/blob/main/CONTRIBUTING.md)
+covers the golden files, measuring a change, the rules for the tables, and
+releasing.
+
+## License
+
+[MIT](https://github.com/redodson01/vim2bat/blob/main/LICENSE)