https://github.com/arcaartem/manage-dotfiles
Lightweight script to help manage dotfiles with `stow`
https://github.com/arcaartem/manage-dotfiles
dotfiles-manager posix-compliant shell-script
Last synced: 8 months ago
JSON representation
Lightweight script to help manage dotfiles with `stow`
- Host: GitHub
- URL: https://github.com/arcaartem/manage-dotfiles
- Owner: arcaartem
- Created: 2025-03-23T13:56:41.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-03-23T13:58:05.000Z (8 months ago)
- Last Synced: 2025-03-23T14:36:38.334Z (8 months ago)
- Topics: dotfiles-manager, posix-compliant, shell-script
- Language: Shell
- Homepage:
- Size: 0 Bytes
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Dotfiles Manager
A flexible and powerful dotfiles management system that supports templating, host-specific configurations, and package-based organization.
## Features
- Template-based configuration files with variable substitution
- Host-specific package overrides
- Package-based organization of dotfiles
- Dry-run mode for safe testing
- Support for multiple package selection
- Built on GNU Stow for reliable symlink management
## Prerequisites
- GNU Stow
- BATS (Bash Automated Testing System) - for running tests
- Light-weight shell templating engine (https://github.com/arcaartem/template)
### Installation
```bash
# On macOS with Homebrew
brew install stow bats
# On Ubuntu/Debian
sudo apt-get install stow bats
```
## Usage
### Basic Commands
```bash
# Build packages (render templates) to ./tmp/build
./manage.sh build
# Render packages directly to dotfiles directory
./manage.sh render
# Preview changes (dry-run)
./manage.sh stow
# Apply changes
./manage.sh stow --apply
# Remove symlinks (dry-run)
./manage.sh unstow
# Remove and reapply symlinks (dry-run)
./manage.sh restow
```
### Package Selection
```bash
# Process all available packages
./manage.sh stow --apply
# Process a single package
./manage.sh stow --apply my-package
# Process multiple packages
./manage.sh stow --apply package1 package2
```
### Host-Specific Configuration
```bash
# Use host-specific packages and config
./manage.sh stow --apply -H my-hostname
```
## Directory Structure
```
.
├── config/ # Configuration files
│ ├── defaults # Default template variables
│ └── hostname.conf # Host-specific template variables
├── packages/
│ ├── common/ # Common packages
│ │ └── package-name/ # Package contents
│ └── host-specific/ # Host-specific packages
│ └── hostname/ # Host-specific overrides
│ └── package-name/ # Override contents
└── src/
├── manage.sh # Main script
└── template.sh # Template processing script
```
## Template Syntax
Templates support variable substitution using `${VARIABLE}` syntax:
```bash
# Example template file
export PATH="${HOME}/.local/bin:${PATH}"
```
Variables can be defined in:
- `config/defaults` - Default values
- `config/hostname.conf` - Host-specific values
## Development
### Running Tests
```bash
# Run all tests
bats test/manage.bats
# Run specific test
bats test/manage.bats -f "test name"
```
### Adding New Tests
Tests are written using BATS. See the existing tests in `test/manage.bats` for examples.
### Adding New Packages
1. Create a new directory under `packages/common/`
2. Add your dotfiles
3. Use templates with `${VARIABLE}` syntax as needed
4. Add host-specific overrides in `packages/host-specific/hostname/` if needed
## License
MIT License