fnb 0.12.0

Fetch'n'Backup - Simple two-step backup tool with rsync

fnb — Fetch'n'Backup

fnb is a simple two-step backup tool, powered by rsync. It gives you two handy commands: fetch (to pull from remote), and backup (to save to somewhere safe).

Under the hood? Just good old rsync — no magic, just sharp automation.

• Simple config. Sharp execution. Safe data.
• Use them one by one, or sync them all in one go.

---

🚀 Features

1. Fetch — Retrieve data from a remote server to your local machine
2. Backup — Save local data to external storage
3. Sync — Run Fetch and Backup together in one go
4. Init — Generate an initial config file (fnb.toml)
5. Structured Logging — Built-in logging with configurable verbosity levels and file output

---

⚙️ Installation

From PyPI (Recommended)

pip install fnb
# または
uv pip install fnb

From Source

git clone https://gitlab.com/qumasan/fnb.git
cd fnb
uv pip install -e .

Requirements: Python 3.12 or higher is required.

---

🧰 使用例

# Initialize configuration files (fnb.toml and .env files)
fnb init

# Check the current config
fnb status

# Fetch: remote -> local
fnb fetch TARGET_LABEL

# Backup: local -> external
fnb backup TARGET_LABEL

# Run Fetch → Backup in one go
fnb sync TARGET_LABEL

# Check version
fnb version

# Logging and Verbosity Control
# Adjust log level for detailed output
fnb fetch TARGET_LABEL --log-level DEBUG
fnb sync TARGET_LABEL --verbose      # Same as --log-level DEBUG
fnb backup TARGET_LABEL --quiet      # Same as --log-level WARNING

# Log files are automatically saved to:
# macOS: ~/Library/Logs/fnb/fnb.log
# Linux: ~/.local/share/fnb/fnb.log

---

🔧 設定ファイル

config.toml

各処理対象のディレクトリごとに fetch / backup の設定を持ちます。

[fetch.SECTION_NAME]
label = "TARGET_LABEL"
summary = "Fetch data from remote server"
host = "user@remote-host"
source = "~/path/to/source/"
target = "./local/backup/path/"
options = ["-auvz", "--delete", '--rsync-path="~/.local/bin/rsync"']
enabled = true

[backup.SECTION_NAME]
label = "TARGET_LABEL"
summary = "Backup data to cloud storage"
host = "none"    # <- ローカル操作
source = "./local/backup/path/"  # <- fetchのtargetパス
target = "./cloud/backup/path/"
options = ["-auvz", "--delete"]
enabled = true

設定ファイルの優先順位（高 → 低）

1. ./fnb.toml ← プロジェクトローカル設定
2. ~/.config/fnb/config.toml ← グローバルユーザー設定（XDG準拠）
3. C:\Users\ユーザー名\AppData\Local\fnb\config.toml ← グローバルユーザー設定（Windowsの場合）
4. ./config/*.toml ← 設定の分割・統合用（開発/運用向け）

---

📊 Logging

fnb includes built-in structured logging powered by loguru. All operations are logged with configurable verbosity levels.

Log Levels

• DEBUG — Detailed debugging information, command traces, and internal state
• INFO — General operational information, task progress, success/failure messages (default)
• WARNING — Important notices, non-critical issues, fallback actions
• ERROR — Error conditions, operation failures, critical issues

Log Output

Console Output (stderr)

• Colored, structured format with timestamps
• User-facing messages on stdout (status, progress)
• Internal logging on stderr (debug, technical details)

Log Files (automatic)

• macOS: ~/Library/Logs/fnb/fnb.log
• Linux: ~/.local/share/fnb/fnb.log
• Windows: %APPDATA%\qumasan\fnb\Logs\fnb.log

File Log Management

• Rotation: Automatic rotation when files reach 10MB
• Retention: Keeps logs for 7 days
• Compression: Old logs compressed with gzip
• Disable: Set FNB_DISABLE_FILE_LOGGING=1 to disable file logging

Command Examples

# Default INFO level logging
fnb sync logs

# Verbose debugging output
fnb fetch logs --verbose
fnb sync logs --log-level DEBUG

# Quiet mode (warnings and errors only)
fnb backup logs --quiet
fnb fetch logs --log-level WARNING

# Custom log level
fnb sync logs --log-level ERROR

---

🔐 Authentication

SSH password input can be automated using pexpect. You can also define connection settings in a .env file if needed. Run fnb init env to create the initial .env file.

---

🆕 What's New in v0.11.2

📖 ReadTheDocs Documentation Platform Integration

• Versioned Documentation - Automatic documentation builds for each Git tag
• Multi-format Output - HTML, EPUB, and HTMLZip formats available
• Version Selector - Easy switching between documentation versions
• Public Documentation - Professional documentation hosting at https://fnb.readthedocs.io/

🔧 Enhanced Documentation Infrastructure

• Automated Builds - Documentation automatically builds on tag push
• Material Theme Support - Full mkdocs-material compatibility with ReadTheDocs
• Stable URLs - Each version accessible at predictable URLs
• Search Integration - Full-text search across all versions

---

🧪 Development

• Python3 - version 3.12 or higher
• uv - package management
• Typer - CLI framework
• Pydantic - config modeling
• pexpect - SSH automation
• python-dotenv - environment variable support
• pytest - testing framework (87% coverage)
• mkdocs-material - documentation with i18n support
• pre-commit - run checks before each commit
• ruff - fast Python linter and formatter
• commitizen - conventional commit tagging and changelog automation
• renovate - automated dependency management

Version Management

This project uses automated semantic versioning with GitLab releases:

# Preview version bump
task version

# Execute version bump and changelog update
task version:bump

# Create GitLab release
task release

# Complete release workflow (test → format → bump → release)
task release:full

Current Version: v0.11.2 - View Release

CI/CD Pipeline

GitLab CI/CD pipeline provides automated testing, building, and deployment:

Stages:

• renovate: Automated dependency management (optional)
• test: Unit tests, code quality, Renovate-specific tests
• docs-quality: Documentation build validation
• build: Package building with uv build
• deploy-test: TestPyPI deployment (automatic on tag push) 🚀
• deploy-prod: PyPI deployment (manual approval for safety)

Automated Workflows:

# Deployment (v0.10.0)
tag push → [Auto TestPyPI] → Local Verification → [Manual PyPI]

# Dependency Management (v0.11.0)
Monday 6am JST → [Renovate Scan] → [Auto MR] → [Enhanced Testing]

Optional CI Variables:

# GitLab Settings → CI/CD → Variables
TESTPYPI_API_TOKEN  # TestPyPI API token for testing releases
PYPI_API_TOKEN      # PyPI API token for production releases
RENOVATE_TOKEN      # GitLab token for automated dependency updates (new in v0.11.0)

Local CI Simulation:

# Run tests as they run in CI (unit tests only)
task test:ci

# Run unit tests only (fast feedback)
task test:unit

# Run integration tests only
task test:integration

# Run all tests
task test

# Verify TestPyPI deployment (v0.10.0)
VERSION=0.11.2 task verify:testpypi

# Dependency management tasks (new in v0.11.0)
task deps:update    # Update all dependencies
task deps:test      # Test with updated dependencies
task deps:security  # Check for security vulnerabilities

Test Structure

Tests are organized into two directories for optimal development workflow:

• tests/unit/: 9 files, 124 tests - Fast unit tests (1.65s)
• tests/integration/: 1 file, 23 tests - Comprehensive workflow tests (3.25s)

Both directory-based and marker-based execution are supported:

# Directory-based (recommended)
task test:unit          # tests/unit/ only
task test:integration   # tests/integration/ only

# Marker-based (backward compatibility)
pytest -m "not integration"  # unit tests
pytest -m "integration"      # integration tests

Test Coverage

Current test coverage is 87% (exceeds target, improved from 83% in v0.10.0) with comprehensive error handling and integration testing:

• backuper.py: 83% - Backup operation failure scenarios
• fetcher.py: 85% - SSH authentication and fetch failures
• cli.py: 99% - CLI command error scenarios
• reader.py: 89% - Configuration reading and validation
• gear.py: 87% - SSH automation with pexpect
• env.py: 68% - Environment variable handling

Integration Testing

Complete integration test suite with 23 tests (100% success rate):

• CLI Workflow Integration: 7 tests covering init → status → fetch/backup/sync workflows
• Multi-Module Integration: 6 tests verifying config → reader → gear → operation flows
• Sync Workflow Integration: 6 tests for complete fetch-then-backup sequences
• End-to-End Integration: 2 tests simulating realistic user workflows
• Test Infrastructure: Strategic mocking, external dependency isolation, reliable deterministic testing

🪪 License

MIT

🛠️ Contributing

This project is maintained in two repositories:

• 🛠️ Development, Issues, Merge Requests: GitLab
• 🌏 Public Mirror and Discussions: GitHub
• 📦 PyPI Package: fnb (v0.11.2)
• 📖 Documentation: ReadTheDocs with versioned documentation
• 📖 Legacy Docs: GitLab Pages (maintained for reference)

Please use GitLab for development contributions, bug reports, and feature requests. For documentation viewing and community discussions, feel free to visit the GitHub mirror.

Development Workflow

See CLAUDE.md for detailed development guidelines including:

• Testing and coverage requirements (83%+)
• Version management and release workflow
• GitLab integration best practices