dotforge

dotforge is a Python CLI for applying a dotfiles manifest: install required system packages and create links for configured files.

Important

Work in progress. This project is not fully completed.

Table of Contents

• Overview
• Requirements
• Quick Start
• Usage
• Development Setup
• Quality Checks
• Project Structure
• Contributing
• Contributors

Overview

• Language: Python
• Package management: uv
• CLI framework: Click
• Current wired commands: install, link

Requirements

• Python 3.12+
• uv

Install uv:

pip install uv

Quick Start

# 1) Clone
git clone https://github.com/aazerra/dotforge.git
cd dotforge

# 2) Sync dependencies and create project environment
uv sync

# 3) Run CLI
python -m forge --help

Usage

Run with module entrypoint:

python -m forge install manifest.yaml
python -m forge link manifest.yaml

Or run the installed script:

dotforge install manifest.yaml
dotforge link manifest.yaml

Manifest file example:

name: my-dotfiles
version: 1.0.0
description: My personal dotfiles
packages:
  - ncmpcpp
  - notion
links:
  - source: nvim
    target: ~/.config/nvim

Development Setup

# Install runtime + dev + test groups
uv sync --group dev --group test

# Optional: install pre-commit hooks
uv run --group dev pre-commit install

Quality Checks

# Tests
python -m pytest -q

# Lint and format
uv run --group dev ruff check .
uv run --group dev black --check .

# Type checking
uv run --group dev mypy

# Run all configured pre-commit hooks
uv run --group dev pre-commit run --all-files

TDD loop:

1. Write or update a test first.
2. Run tests and watch it fail.
3. Implement the smallest change.
4. Run tests again until green.
5. Refactor with checks staying green.

Project Structure

.
├── forge/
│   ├── commands/
│   ├── core/
│   ├── exceptions/
│   └── types/
├── tests/
├── manifest.yaml
├── pyproject.toml
└── uv.lock

Contributing

Contributions are welcome.

1. Fork the repository.
2. Create a feature branch.
3. Add or update tests for behavior changes.
4. Run quality checks locally.
5. Open a pull request.

Contributors

Thanks to everyone who has contributed to this project:

See the full list of contributors →