Skip to content

docs: streamline documentation for personal use #71

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
maxrantil merged 1 commit into from
Nov 10, 2025
Merged

docs: streamline documentation for personal use #71

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
191 changes: 57 additions & 134 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,169 +1,92 @@
# Dotfiles

Minimal dotfiles for Ubuntu servers. Optimized for development over SSH.
Minimal symlink-based dotfiles for SSH development. XDG-compliant, distro-aware, <100ms startup.

## What's Inside

**Shell Environment:**
- `.zshrc` - Zsh config with vi mode, starship prompt, fzf integration
- `.zprofile` - Zsh profile (login shell setup)
- `.aliases` - Shell aliases with distro detection (Debian/Arch)
- `distro/` - Distro-specific aliases (apt/pacman)
- `inputrc` - Readline configuration

**Development Tools:**
- `init.vim` - Neovim config (Gruvbox, git, FZF, linting)
- `.tmux.conf` - Tmux config (backtick prefix, vim nav, persistence)
- `.gitconfig` - Git config with delta pager, shortcuts (gs, ga, gc)
- `.gitconfig.local.example` - Template for personal git info
- `starship.toml` - Starship prompt configuration

**Bookmark System:**
- `bm-dirs` - Directory bookmarks (cf → ~/.config)
- `bm-files` - File bookmarks (ez → ~/.zshrc)
- `generate-shortcuts.sh` - Auto-generate shortcuts from bookmarks

**Management:**
- `install.sh` - Symlink installer with automatic backups
- `rollback.sh` - Restore from backup
- `tests/` - Docker-based automated testing

## Quick Install

```bash
git clone https://github.com/maxrantil/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh
```

## Rollback

If installation causes issues, restore your original configuration from the automatic backup:

```bash
# Interactive rollback with confirmation
./rollback.sh

# Automatic rollback without prompts
./rollback.sh -y

# Preview changes without applying
./rollback.sh --dry-run
# Set your git identity
cp .gitconfig.local.example ~/.gitconfig.local
vim ~/.gitconfig.local # Add name, email, GPG key
```

The rollback script:
- Finds the latest backup directory (`.dotfiles_backup_*`)
- Removes current dotfiles symlinks
- Restores original files with preserved permissions
- Cleans up the empty backup directory

## Post-Install Setup

### Git User Configuration

The dotfiles include a shared `.gitconfig` but require you to set your personal information:
## Daily Usage

```bash
# Copy the example template
cp ~/.dotfiles/.gitconfig.local.example ~/.gitconfig.local

# Edit with your information
vim ~/.gitconfig.local
# Set: name, email, and optionally GPG signingkey
```
# Edit dotfiles (auto-tracked via symlinks)
ez # Edit .zshrc
vim ~/.dotfiles/.aliases
git -C ~/.dotfiles add . && git -C ~/.dotfiles commit -m "update" && git -C ~/.dotfiles push

This keeps your personal information private and out of the tracked repository.

## What's Included

- **Zsh** - Vi mode, starship prompt, fzf, auto-detects distro
- **Tmux** - Backtick prefix, vim navigation, session persistence
- **Neovim** - Gruvbox theme, git integration, FZF, linting
- **Git** - Delta pager, shortcuts (gs, ga, gc, etc.)
- **Bookmarks** - Quick navigation (cf → ~/.config, sc → ~/.local/bin)

## Key Features

- **Symlink-based** - Edit once, auto-tracked in git
- **Distro-aware** - Debian (apt) and Arch (pacman) aliases
- **Tmux ready** - Persistent sessions survive SSH disconnects
- **Vi everywhere** - Consistent keybindings across zsh/tmux/vim

## Development & Testing
# Sync on other machines
git -C ~/.dotfiles pull

### Automated CI Testing
# Tmux sessions
ts project # New session
` d # Detach (backtick + d)
ta project # Re-attach

Every pull request automatically runs:
- **ShellCheck** - Linting for shell scripts
- **shfmt** - Shell formatting validation
- **Installation Test** - Verifies install.sh creates all required symlinks (~30 seconds)
# Rollback if needed
./rollback.sh # Interactive restore from backup
```

### Quick Testing (30 seconds)
## Testing

```bash
# Run automated Docker tests
# Quick Docker test (30s)
./tests/docker-test.sh

# Interactive shell for debugging
# Interactive debugging
./tests/docker-test.sh --interactive

# Run comprehensive test suite standalone
./tests/installation-test.sh
```

**Comprehensive test coverage includes:**
1. **Symlink verification** - All expected dotfiles properly linked
2. **Symlink target validation** - Links point to correct source files
3. **ZDOTDIR compliance** - .zshrc correctly placed in XDG directory
4. **Conditional file handling** - Optional files (.gitconfig, inputrc) tested
5. **Idempotency** - Running install.sh twice produces identical results
6. **Backup functionality** - Existing files safely backed up before linking
7. **Rollback functionality** - Restoration from backup with permission preservation
8. **Shortcut generation** - Bookmark shortcuts created from bookmarks file
9. **Environment isolation** - Tests run in clean environment
10. **Performance regression** - Install completes within 30-second threshold

All tests include detailed diagnostics and colored output for easy debugging.

### Full Integration Testing

For comprehensive VM-based testing, see the [vm-infra repository](https://github.com/maxrantil/vm-infra).

```bash
# Test with local dotfiles (from vm-infra repo)
# VM integration test (5min, from vm-infra repo)
./provision-vm.sh test-vm --test-dotfiles ../dotfiles
```

### Maintaining CI Tests

When modifying `install.sh`:

**Adding critical symlinks** (required for shell function):
1. Add symlink creation to `install.sh`
2. Update `.github/workflows/shell-quality.yml` verification step
3. Document why it's critical in workflow comments

**Adding optional symlinks** (enhancements):
1. Add symlink creation to `install.sh`
2. No CI update needed (tested in VM tier)
3. Document as optional in workflow comments

**Critical vs Optional:**
- **Critical**: Shell won't function without it (.zshrc, .aliases, nvim, tmux, starship)
- **Optional**: Nice-to-have enhancements (.gitconfig, .zprofile, inputrc, shortcuts)

### Troubleshooting Installation Test Failures

**CI Error: "ERROR: .zshrc not linked"**
- **Cause**: install.sh failed to create expected symlink
- **Debug**: Run `bash install.sh` in clean test directory
- **Check**: Verify source file exists in repository

**CI Error: "ERROR: Found broken symlinks"**
- **Cause**: Symlink points to non-existent file
- **Debug**: Check if target file was renamed/removed in recent commits
- **Fix**: Update install.sh symlink path or restore missing file

## Usage

```bash
# Update dotfiles
cd ~/.dotfiles
vim .aliases
git add . && git commit -m "update" && git push

# Sync on other machines
cd ~/.dotfiles && git pull
```

## Tmux Quick Start
**CI automatically runs:** ShellCheck, shfmt, installation tests on every PR.

```bash
ts project # New session
` d # Detach (backtick + d)
ta project # Re-attach
```
## Key Features

Symlinks keep everything in sync. No reinstall needed.
- **Fast** - <100ms shell startup with prompt caching
- **Secure** - Pre-commit hooks (shellcheck, shfmt, gitleaks)
- **Vi everywhere** - Consistent keybindings (zsh/tmux/vim)
- **Tmux ready** - Sessions persist through SSH disconnects
- **XDG compliant** - .zshrc lives in $XDG_CONFIG_HOME/zsh

## Troubleshooting

Having issues? See the [Troubleshooting Guide](TROUBLESHOOTING.md) for solutions to common problems.
See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues and solutions.

---

_Last updated: 2025-11-04_
_Minimal by design. Personal use only._
Loading
Loading