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

sh -c "$(curl -fsLS https://raw.githubusercontent.com/artefactory/artefiles/main/install.sh)"

This is the recommended path. The script:

1. Installs GitHub CLI if not already present
2. Authenticates you with GitHub (interactive browser flow, or reads a token from the environment — see below)
3. Installs chezmoi and runs chezmoi init --apply

Why not curl get.chezmoi.io | sh ... init --apply directly? .chezmoi.toml.tmpl calls gh api user at init time to pre-populate your name and email. GitHub CLI must be installed and authenticated before chezmoi init runs. install.sh enforces that order; the chezmoi-direct path does not.

Non-interactive Environments (Codespaces / CI)

For headless environments where a browser login is not possible, set a GitHub token before running the script:

export GH_TOKEN=ghp_your_token_here
sh -c "$(curl -fsLS https://raw.githubusercontent.com/artefactory/artefiles/main/install.sh)"

GITHUB_TOKEN is also accepted and is set automatically in GitHub Actions. In Codespaces the token is already in the environment, so no extra configuration is needed beyond adding this repository as your dotfiles source.

GitHub Codespaces

These dotfiles can automatically bootstrap your GitHub Codespace environment:

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

Learn more about Codespaces dotfiles in the official documentation.

Manual / Advanced Installation

If you prefer to manage prerequisites yourself before running chezmoi directly:

1. Install Homebrew (macOS):

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

2. Install GitHub CLI using your preferred method for your platform.

3. Authenticate with GitHub CLI following the official instructions, or set GH_TOKEN in your environment.

4. Install these dotfiles directly with chezmoi:

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

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, git-extras	Advanced version control tooling
atuin	Atuin	Shell history sync across machines
python_dev	nbdime, pre-commit (via uv)	Python/Jupyter development tools
gcloud	Google Cloud SDK	Google Cloud CLI (cask on darwin, manual install on linux)
colima	Colima	Container runtime (darwin only)
multiplexer	Zellij	Terminal multiplexer
aerospace	AeroSpace	Tiling window manager (darwin only)
onepassword	1Password, 1Password CLI	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, Git LFS, and git-extras (~80 helper subcommands like git summary, git undo, git ignore, git wip)
• 📊 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) (requires terminal module)

VS Code Configuration

• ~/.config/Code/User/settings.json (Linux) — Default VS Code settings (Catppuccin theme, FiraCode font, fish terminal, Ruff formatter). Created on first apply only; your edits are never overwritten on chezmoi update.
• ~/Library/Application Support/Code/User/settings.json (macOS) — Same default VS Code settings as the Linux path above. Created on first apply only; never overwritten on chezmoi update.

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)

Customizing Starship

• Configuration guide - module reference and syntax
• Presets gallery - ready-made prompt styles
• Catppuccin theme - palette currently in use

Development Tools

• ~/.config/bat/config - Syntax highlighter configuration (Bat Documentation)
• ~/.config/direnv/direnvrc - Environment management (Direnv Documentation)
• ~/.config/uv/uv.toml - Python package manager configuration (uv Documentation)
• ~/.config/atuin/config.toml - Shell history sync (Atuin Documentation) (requires atuin module)
• ~/.config/nvim/init.lua - Neovim editor configuration (Neovim Documentation) (requires editor module)

macOS Window Manager

• ~/.config/aerospace/aerospace.toml (macOS) - AeroSpace window manager (AeroSpace Documentation) (requires macos_desktop module)

Prerequisites

• A GitHub account (for git and GitHub-related features)
  • For non-interactive environments, set GH_TOKEN or GITHUB_TOKEN before installation
• SSH keys added to your GitHub account (instructions)

After installation, you will need to change your default shell to Fish to get the full experience — see Post-Installation Steps.

Common Tasks

Task	Command
Update dotfiles	chezmoi update
Edit config	chezmoi edit <path>
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/command-overview/

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/
  ├── aerospace/       # macOS window manager (macos_desktop module)
  ├── atuin/           # Shell history sync (atuin module)
  ├── bat/             # Syntax highlighting
  ├── direnv/          # Environment management
  ├── fish/            # Shell configuration
  │   ├── config.fish  # Main shell configuration
  │   ├── aliases.fish # Shell aliases and functions
  │   └── functions/   # Custom fish functions
  ├── ghostty/         # Terminal emulator (terminal module)
  ├── nvim/            # Editor configuration (editor module)
  ├── uv/              # Python package manager
  └── starship.toml    # Prompt configuration

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

Post-Installation Steps

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

install.sh does not change your default shell — this requires sudo and is a deliberate user choice.

Set Fish as your default login shell after installation:

macOS:

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

Linux:

chsh -s $(which fish)

You may need to log out and back in for the shell change to take effect. 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>

Detailed Documentation

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

License

MIT