Dotzilla

A powerful, Git-inspired dotfiles manager with symbolic linking capabilities.

Table of Contents

• Dotzilla
  • Table of Contents
  • Overview
  • Features
  • Installation
    • From Source
    • Using Cargo
  • Usage
    • Initialize a Repository
    • Adding Dotfiles
    • Staging Files
    • Unstaging Files
    • Creating Symlinks
    • Viewing Status
    • Listing Tracked Files
    • Comparing Files
  • Command Reference
  • Example Workflow
  • Shell Completion
  • Contributing
  • License

Overview

Dotzilla is a command-line tool designed to help you manage your dotfiles with a workflow inspired by Git. It allows you to track, stage, and link dotfiles between a central repository and their original locations on your system.

Features

• Repository Management: Initialize and maintain a centralized dotfiles repository
• Tracking System: Add and track dotfiles in your repository
• Staging Workflow: Stage files before linking, similar to Git's staging area
• Symbolic Linking: Create symlinks from your repository to system locations
• Diff Support:
  • Compare tracked dotfiles with their system originals
  • Support for both file and directory diffs
  • Word-by-word diff option
  • Integration with external diff tools (vimdiff, meld, kdiff3, VS Code)
• Status Reporting: View the status of your tracked and staged dotfiles
• Shell Completion: Support for bash, zsh, fish, and other shells

Installation

From Source

# Clone the repository
git clone https://github.com/snakeice/dotzilla.git
cd dotzilla

# Build the project
cargo build --release

# The binary will be available at target/release/dotzilla
# Optionally, move it to a directory in your PATH
cp target/release/dotzilla ~/.local/bin/

Using Cargo

cargo install dotzilla-cli

Usage

Initialize a Repository

Create a new dotfiles repository:

dotzilla init ~/dotfiles

Adding Dotfiles

Add a dotfile to tracking:

dotzilla add ~/.bashrc

This copies the file to your dotfiles repository and begins tracking it.

Staging Files

Stage a dotfile for linking:

dotzilla stage .bashrc

Unstaging Files

Remove a file from the staging area:

dotzilla unstage .bashrc

Creating Symlinks

Link all staged dotfiles to their original locations:

dotzilla link

This creates symbolic links from your dotfiles repository to the original locations.

Viewing Status

Check the status of your dotfiles:

dotzilla status

Listing Tracked Files

List all tracked dotfiles:

dotzilla list

Comparing Files

Compare a tracked dotfile with its system original:

# Basic diff
dotzilla diff .bashrc

# Word-by-word diff
dotzilla diff .bashrc --word

# Using an external diff tool
dotzilla diff .bashrc --tool vimdiff
dotzilla diff .bashrc --tool meld
dotzilla diff .bashrc --tool vscode

# Directory diff
dotzilla diff .config

Command Reference

Example Workflow

1. Initialize your dotfiles repository:

   dotzilla init ~/dotfiles
   

2. Add some dotfiles:

   dotzilla add ~/.bashrc
   dotzilla add ~/.vimrc
   dotzilla add ~/.config/nvim
   

3. Check their status:

   dotzilla status
   

4. Stage files you want to link:

   dotzilla stage .bashrc
   dotzilla stage .vimrc
   

5. Create symlinks:

   dotzilla link
   

6. Later, if you make changes to files in their original locations, compare them:

   dotzilla diff .bashrc
   

7. Add the updated file to incorporate changes:

   dotzilla add ~/.bashrc
   

Shell Completion

Dotzilla supports shell completion for various shells, making it easier to use the command-line interface.

Generate shell completion scripts:

# For Bash
dotzilla completion bash > ~/.local/share/bash-completion/completions/dotzilla

# For Zsh
dotzilla completion zsh > ~/.zfunc/_dotzilla

# For Fish
dotzilla completion fish > ~/.config/fish/completions/dotzilla.fish

Make sure the respective directories exist and are in your shell's completion path.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.