How dob9601/jointhedots works
1. What this repo is
- jointhedots is a single Rust CLI binary for managing dotfiles from a Git repository.
- There is no server component; the architecture centers on local filesystem operations plus Git operations against a remote repo.
2. Top-level entry points
- src/main.rs is the executable entry.
- src/cli.rs defines the command-line interface and dispatches to the subcommands.
- src/lib.rs exposes the reusable application logic shared by the binary and internal modules.
3. Primary user workflows
- The CLI exposes three core paths: install, interactive, and sync.
- install applies a manifest-driven dotfile repo onto the user’s machine.
- interactive is the same install pipeline with user selection/prompting layered on top.
- sync pushes local dotfile changes back into the repository and reconciles with Git.
4. Manifest-driven configuration
- The repo expects a jtd.yaml manifest in the root of a dotfile repository.
- src/structs/manifest.rs and src/structs/dotfile.rs model the manifest entries: source file, target path, and optional install hooks.
- src/structs/config.rs represents global behavior such as commit prefix and squash behavior.
5. Install-step and state model
- The manifest can include pre_install and post_install shell commands, so install is not just file copying; it is a controlled execution pipeline.
- src/structs/metadata.rs likely stores install-state metadata, including hashes of install steps so they only rerun when the manifest changes.
- This creates a durable boundary between “declared desired state” in the manifest and “what has already been applied” on the host.
6. Filesystem side of the architecture
- Install operations map repo files into user destinations such as ~/.config/....
- The core filesystem boundary is between the checked-out dotfile repository and the user’s home directory.
- Utility code in src/utils.rs likely handles path resolution, command execution, and shared filesystem helpers.
7. Git subsystem
- src/git/operations.rs and src/git/remote.rs isolate Git-specific behavior from the rest of the app.
- This layer is responsible for repo state checks, committing, merging/syncing, and pushing or pulling to a remote.
- The rest of the application talks to this module rather than dealing with Git details directly.
8. Install and sync data flow
- install starts by loading and validating the manifest, checking whether the repo is ahead/behind where relevant, then executing install hooks and placing files.
- sync flows in the opposite direction: detect local file changes, turn them into Git commits, and push them to the configured remote.
- The README implies sync behavior is deterministic and can be non-interactive for scripting.
9. Interactive mode
- src/subcommands/interactive.rs adds a user-choice layer over the same underlying install engine.
- It is not a separate subsystem; it is a UI wrapper that narrows which dotfiles are processed.
10. Validation and schema support
- src/dotfile_schema.json provides JSON Schema for editor support and manifest validation.
- src/jtd-wrapper.sh suggests a bootstrap/wrapper path used for one-line installation or execution packaging.
- These are support artifacts around the manifest contract rather than runtime business logic.
11. Logging and observability
- src/log.rs centralizes logging behavior for CLI output.
- This is important because the app performs multi-step operations with external side effects: file writes, shell commands, and Git changes.
12. Architecture boundaries to draw
- Draw three main boundaries: the CLI/front end, the dotfile domain + install/sync engine, and the Git/filesystem side effects.
- Persistent inputs/outputs are: jtd.yaml, installed metadata, user home files, and the remote Git repository.
- The repo is essentially a deterministic orchestration layer that translates manifest state into local installs and Git-backed synchronization.
Main entry points: install.rs Install · sync.rs Sync · manifest.rs Manifest · lib.rs Lib
Components 16
CLI Front End
Command entrypoints and user-facing subcommands.
- Main · Executable entrypoint.
src/main.rs - CLI · Parses commands and dispatches subcommands.
src/cli.rs - Interactive · Interactive selection layered over install.
src/subcommands/interactive.rs
Dotfile Domain
Manifest-driven install and sync orchestration.
- Install · Applies manifest-defined dotfiles and hooks.
src/subcommands/install.rs - Sync · Reconciles local changes back into Git.
src/subcommands/sync.rs - Lib · Reusable application logic for the binary and modules.
src/lib.rs - Manifest · Repository manifest describing dotfiles and hooks.
src/structs/manifest.rs - Dotfile · Represents a source file, target path, and install hooks.
src/structs/dotfile.rs - Config · Global behavior such as commit prefix and squash settings.
src/structs/config.rs - Metadata · Tracks applied install state and step hashes.
src/structs/metadata.rs - Utils · Shared helpers for paths, execution, and filesystem work.
src/utils.rs
Git Layer
Git-specific operations and remote handling.
Support Artifacts
Schema, wrapper, and logging support around the main flows.
Connections 27
- Main → CLI: starts · Binary enters through CLI parsing and dispatch.
- CLI → Install: dispatches · Routes the install command.
- CLI → Interactive: dispatches · Routes the interactive command.
- CLI → Sync: dispatches · Routes the sync command.
- Interactive → Install: wraps · Interactive mode reuses the install pipeline.
- Install → Manifest: loads · Install begins by reading the manifest.
- Install → Dotfile: applies · Uses dotfile entries to place files and hooks.
- Install → Metadata: updates · Persists install state and step hashes.
- Install → Config: reads · Uses global behavior settings.
- Install → Utils: uses · Relies on shared filesystem and process helpers.
- Install → Git Ops: checks · May inspect repository state before applying changes.
- Sync → Git Ops: commits · Turns local changes into git operations.
- Sync → Remote: pushes · Synchronizes with the configured remote.
- Sync → Utils: uses · Shares path and filesystem helpers.
- Sync → Dotfile: tracks · Uses dotfile definitions when reconciling changes.
- Manifest → Dotfile: contains · Manifest is composed of dotfile entries.
- Manifest → Config: includes · Manifest references global behavior settings.
- Manifest → Metadata: drives · Manifest changes influence applied-state metadata.
- Git Ops → Remote: uses · Git operations are isolated from remote handling.
- Logging → Install: observes · Logs the install pipeline.
- Logging → Sync: observes · Logs the sync pipeline.
- Schema → Manifest: validates · Schema supports manifest validation and editor tooling.
- Wrapper → Main: boots · Wrapper script can launch the CLI entrypoint.
- Lib → Install: exports · Shared core exposes install logic to the binary.
- Lib → Sync: exports · Shared core exposes sync logic to the binary.
- Lib → Git Ops: reuses · Centralizes Git access through shared application logic.
- Lib → Utils: reuses · Shares common helpers across modules.