Skip to content

For Developers

Clone the repository if you want to run fnb from source, tweak its behavior, or debug it — without installing the package.

Clone and Set Up

git clone https://gitlab.com/qumasan/fnb.git
cd fnb

uv sync --all-groups

This creates a local .venv and installs fnb in editable mode along with all dev/docs dependencies — no separate pip install -e . step needed.

Run from Source

Use uv run to execute the CLI against your local checkout, picking up any changes to the source immediately:

uv run fnb --help
uv run fnb version
uv run fnb init
uv run fnb fetch TARGET_LABEL --dry-run

Because uv sync installs fnb in editable mode, edits under src/fnb/ take effect the next time you run uv run fnb ... — no reinstall required.

Tweaking and Debugging

  • Source layout: src/fnb/cli.py is the entry point; each command (fetch, backup, upload, sync, status, init) delegates to its own module (fetcher.py, backuper.py, uploader.py, reader.py, generator.py)
  • Verbose logs: add --verbose (or --log-level DEBUG) to any command to see internal logging on stderr
  • Log files: structured logs are also written to a platform-specific location (see fnb --help output, or src/fnb/logger.py) — useful when debugging a run after the fact
  • Dry runs: --dry-run is supported on fetch/backup/upload/sync and is the safest way to poke at behavior without touching real files
  • Self-tests: several modules (e.g. src/fnb/gear.py, src/fnb/fetcher.py) have a if __name__ == "__main__": block you can run directly with uv run python src/fnb/gear.py for a quick manual check against examples/config.toml

Running the Test Suite

uv run pytest tests/unit/test_cli.py::test_version_command  # a single test
task test:unit                                                # all unit tests

Next Steps

If you're planning to submit changes back to the project (not just running fnb locally), see the Contributor Guide for the full workflow: branching, coding standards, and how to open a merge request.