Artefiles

A cross-platform dotfiles template that provides a default and sane configuration for a modern development environment. Managed with chezmoi, these dotfiles deliver a consistent, opinionated setup focused on productivity and modern tooling.

Philosophy

This repository is designed to give you a batteries-included development environment that:

• Uses Fish Shell for intelligent autosuggestions and superior user experience
• Leverages modern Rust-based Unix tools (eza, bat, fd, rg) for better performance and UX
• Provides consistent configuration across macOS and Linux platforms
• Offers a modular architecture: a core layer is always installed, and additional modules are opt-in

Modern terminal setup with Fish shell, Starship prompt, and Rust-based tools

Quick Start 🚀

macOS Prerequisites

⚠️ Important for macOS users: Before installing these dotfiles, you must first:

1. Install Homebrew by running:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install GitHub CLI using Homebrew:

   brew install gh

3. Authenticate with GitHub:

   gh auth login

These steps are essential as the dotfiles rely heavily on Homebrew for package management on macOS.

Installation

Using Bash/Zsh/Sh

sh -c "$(curl -fsLS get.chezmoi.io)" -- -b $HOME/.local/bin init --apply artefactory/artefiles

Using Fish Shell

curl -fsLS get.chezmoi.io | sh -s -- -b ~/.local/bin init --apply artefactory/artefiles # Fish shell requires this pipe syntax

GitHub Codespaces Support

These dotfiles can automatically bootstrap your GitHub Codespace environment. To use them:

1. Add this repository as your dotfiles in your GitHub Codespaces settings
2. Create a new codespace - it will automatically apply these dotfiles

Learn more about Codespaces dotfiles in the official documentation.

Modular Architecture 🧩

Artefiles uses a core + opt-in modules design. During chezmoi init, you select which modules to enable via an interactive prompt.

Core (always installed)

Fish, Starship, Git, bat, eza, fd, fzf, ripgrep, zoxide, rip2, dust, bottom, direnv, uv, Rust, FiraCode Nerd Font, VS Code.

Optional Modules

Module	Contents	Description
editor	Neovim	Terminal editor with nvim aliases
terminal	Ghostty	Modern GPU-accelerated terminal emulator
git_advanced	jj, mergiraf, difftastic, git-cliff, git-lfs	Advanced version control tooling
atuin	Atuin	Shell history sync across machines
python_dev	nbdime, pre-commit (via uv)	Python/Jupyter development tools
cloud	gcloud, Colima	Cloud SDK and container runtime
multiplexer	Zellij	Terminal multiplexer
macos_desktop	AeroSpace, 1Password, 1Password CLI	macOS window manager and password manager (darwin only)

Changing Modules

Re-run chezmoi init to update your module selection, then chezmoi apply.

What's Included 📦

Core Features

• 🐟 Fish Shell - A smart command-line shell that suggests commands as you type and has better tab completion than traditional shells
• ⚡ Starship - A customizable terminal prompt that shows useful information like git status, programming language versions, and execution time
• 🔍 Modern CLI Tools - Faster, more user-friendly replacements for traditional Unix commands:
  • bat - Enhanced version of cat with syntax highlighting and line numbers
  • eza - Better ls with colors, git status, and tree view
  • fd - Faster, easier-to-use alternative to find for searching files
  • fzf - Fuzzy finder for quickly searching through files and command history
  • rip - Safe rm replacement with a recoverable graveyard
  • ripgrep - Lightning-fast text search across files
• 🌟 Catppuccin - A beautiful, consistent color theme applied across all tools for a cohesive look

Optional Module Highlights

• 📝 Neovim (editor) - A powerful text editor with syntax highlighting, plugins, and modern features
• 🔄 Advanced Git (git_advanced) - Jujutsu, mergiraf, difftastic, git-cliff, and Git LFS
• 📊 Jupyter Notebook Support (python_dev) - nbdime and pre-commit via uv
• 🐋 Container Development (cloud) - Colima for running Docker containers on macOS without Docker Desktop
• ⏰ Shell History (atuin) - Atuin syncs your command history across machines with powerful search
• 📁 Smart Navigation - Zoxide learns your most-used directories for instant navigation

What Files Will Be Created/Modified 📋

⚠️ Important: These dotfiles do NOT modify your shell startup files (.profile, .zprofile, etc.). To benefit from the Fish shell configuration, you must manually change your default shell (see Post-Installation Steps).

Git Configuration

• ~/.gitconfig - Git configuration with modern defaults (Git Documentation)
• ~/.gitattributes_global - Global attributes for merge drivers and file handling

Terminal Configuration

• ~/.config/ghostty/config - Ghostty terminal configuration (Ghostty Documentation)

Fish Shell Configuration (Fish Shell Documentation)

• ~/.config/fish/config.fish - Main Fish shell configuration
• ~/.config/fish/aliases.fish - Shell aliases and functions
• ~/.config/fish/conf.d/artefiles_abbrs.fish - Fish abbreviations managed by chezmoi
• ~/.config/fish/fish_plugins - Fish plugin list
• ~/.config/fish/functions/fish_title.fish - Terminal title function
• ~/.config/fish/functions/smart_bat.fish - Enhanced bat function (VSCode-aware)
• ~/.config/fish/functions/dotfiles_doctor.fish - Health check function

Shell Prompt

• ~/.config/starship.toml - Shell prompt configuration (Starship Documentation)

Development Tools

• ~/.config/bat/config - Syntax highlighter configuration (Bat Documentation)
• ~/.config/direnv/direnvrc - Environment management (Direnv Documentation)
• ~/.config/atuin/config.toml - Shell history sync (Atuin Documentation)
• ~/.config/nvim/init.lua - Neovim editor configuration (Neovim Documentation)
• ~/.config/jj/config.toml - Jujutsu configuration (Jujutsu Documentation)

macOS Window Manager

• ~/.config/aerospace/aerospace.toml - AeroSpace window manager (AeroSpace Documentation) (macOS only)

Prerequisites ✅

For All Platforms

• A GitHub account (for git and GitHub-related features)

  • GitHub CLI authentication will be handled automatically during installation
  • For non-interactive environments, set GH_TOKEN environment variable before installation

• SSH keys added to your GitHub account (instructions)

• Set Fish as your default login shell (required to use the Fish config). No zsh script switches shells for you.

  macOS:

  command -v fish | sudo tee -a /etc/shells
  chsh -s $(brew --prefix)/bin/fish

  Linux:

  chsh -s $(which fish)

  Note: You may need to log out and back in for the shell change to take effect.

macOS Specific

• Homebrew package manager (see macOS Prerequisites above)
• GitHub CLI installed via Homebrew
• Note: Many tools in these dotfiles depend on Homebrew-installed packages on macOS

Common Tasks 🛠️

Task	Command
Update dotfiles	chezmoi update
Edit config	chezmoi edit ~/.config/file
Health check	dotfiles_doctor
New Python project	mkdir project && cd project && echo 'layout uv' > .envrc && direnv allow

Chezmoi Basics 🧰

Chezmoi is the manager for these dotfiles. Main docs: https://www.chezmoi.io/user-guide/

Task	Command
See pending changes	chezmoi status
Inspect diffs	chezmoi diff
Edit a file	chezmoi edit ~/.config/fish/config.fish
Apply changes	chezmoi apply
Update from repo	chezmoi update

Remove All Chezmoi-Managed Files (Danger)

Review first:

chezmoi managed -p absolute

Remove all managed files, then remove chezmoi state/source:

chezmoi managed -p absolute -0 | xargs -0 chezmoi destroy --force
chezmoi purge --force

Configuration Structure 📁

~/.config/
  ├── fish/            # Shell configuration
  │   ├── config.fish  # Main shell configuration
  │   ├── aliases.fish # Shell aliases and functions
  │   └── functions/   # Custom fish functions
  ├── nvim/            # Editor configuration
  ├── direnv/          # Environment management
  ├── bat/             # Syntax highlighting
  └── starship.toml    # Prompt configuration

~/.ssh/config          # SSH configuration
~/.config/ghostty/config # Terminal configuration
~/.gitconfig          # Git configuration

Post-Installation Steps 📝

1. Change Default Shell to Fish (Required for Full Experience)

If you skipped the prerequisite step, set Fish as your default shell now (see Prerequisites).
If you're using VS Code or another IDE, fully quit and reopen it so the Fish profile shows up in the terminal list.

2. Set up shell history sync:

atuin register  # New account
atuin login     # Existing account

3. Initialize cloud tools (if needed):

gcloud init  # Set up Google Cloud SDK

4. Restart your terminal or IDE

Restart your terminal (or fully quit and reopen your IDE if using VS Code, Cursor, etc.) for all changes to take effect.

Need Help? 🤔

• Run dotfiles_doctor to check your installation
• See chezmoi help for dotfiles management
• Check the CHEATSHEET.md for more commands
• Reset a file: chezmoi apply --force ~/.path/to/file

Detailed Documentation 📚

• CHEATSHEET.md - Common commands and shortcuts
• CHANGELOG.md - Version history and updates

License 📄

MIT