https://github.com/peter-bread/.dotfiles
Managing my dotfiles
https://github.com/peter-bread/.dotfiles
configuration dotfiles git linux macos skhd starship symlinks wezterm zsh
Last synced: about 2 months ago
JSON representation
Managing my dotfiles
- Host: GitHub
- URL: https://github.com/peter-bread/.dotfiles
- Owner: peter-bread
- Created: 2024-02-19T21:45:55.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-02-20T00:43:58.000Z (3 months ago)
- Last Synced: 2026-02-20T04:45:15.905Z (3 months ago)
- Topics: configuration, dotfiles, git, linux, macos, skhd, starship, symlinks, wezterm, zsh
- Language: Shell
- Homepage:
- Size: 386 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 37
-
Metadata Files:
- Readme: README.md
- Changelog: newsboat/config
Awesome Lists containing this project
README
# .dotfiles
---
Managing my dotfiles for MacOS and Linux.
---
## Contents
- [Install](#install)
- [File Structure](#file-structure)
- [Neovim](#neovim)
## Install
### TL;DR
For [me](https://github.com/peter-bread), on a new system run the following:
```bash
curl -fsSL https://raw.githubusercontent.com/peter-bread/.dotfiles/refs/heads/main/install |
bash -s -- --prime --modules --pkgs --github --nvim peter.nvim
```
Or:
```bash
wget -qO- https://raw.githubusercontent.com/peter-bread/.dotfiles/refs/heads/main/install |
bash -s -- --prime --modules --pkgs --github --nvim peter.nvim
```
### Details
Read [install](./install) script help information.
```text
Bootstrap script.
Without any options provided, this script will check if required tools are
installed and will then clone or pull dotfiles repository to ~/.dotfiles.
Options can be provided to enable extra functionality.
Usage:
./install [--prime] [--modules] [--pkgs] [--github] [--nvim ] [-h | --help]
Options:
--prime Ensure system has required packages installed
--modules Install modules from MANIFEST.* files
--pkgs Install packages
--github Authenticate with GitHub on this device
--nvim Clone Neovim config as specified by
The argument can be one of:
- A short name (e.g. "peter.nvim"), resolved as:
https://github.com/peter-bread/.git
- A full "owner/repo" pair (e.g. "someone/other.nvim"), resolved as:
https://github.com//.git
- A full Git URL (e.g. "https://github.com/user/repo.git"), HTTPS or SSH, used as-is
-h, --help Print this help message
Environment Variables:
These variables mirror the options above. Flags provided on the command line
take precedence over environment variables. All boolean variables default to 0
(disabled) unless otherwise noted.
Option Flags (0 = disable, 1 = enable):
PRIME Enable system bootstrap to ensure required packages are installed
MODULES Install modules from MANIFEST.* files
PKGS Install packages
GITHUB Authenticate with GitHub on this device
Option Arguments (string; default = empty):
NVIM Neovim configuration repository to clone.
Logging and Output:
ENABLE_COLOR Enable colored logging output (default: 1)
ENABLE_DEBUG Enable debug logging (default: 0)
Developer / Advanced:
DEV_USE_LOCAL Developer mode: do not attempt to clone/pull dotfiles repo.
Useful when testing WIP scripts in a Docker container.
```
Ensure `bash` is available.
Download and execute [`install`](./install).
If on a super minimal system, you may need to download on a another machine and
transfer with a USB.
### Default Behaviour
If no options are provided, the script will:
1. Check requirements (will exit if any errors are reported)
1. Clone or update existing `~/.dotfiles` repo
Using `curl`:
```bash
curl -fsSL https://raw.githubusercontent.com/peter-bread/.dotfiles/refs/heads/main/install | bash
```
Using `wget`:
```bash
wget -qO- https://raw.githubusercontent.com/peter-bread/.dotfiles/refs/heads/main/install | bash
```
### Options
Using `curl`:
```bash
curl -fsSL https://raw.githubusercontent.com/peter-bread/.dotfiles/refs/heads/main/install |
bash -s -- [options]
```
Using `wget`:
```bash
wget -qO- https://raw.githubusercontent.com/peter-bread/.dotfiles/refs/heads/main/install |
bash -s -- [options]
```
### Install without piping into bash
The following examples will just print help information.
Using `curl`:
```bash
curl -fsSLo install https://raw.githubusercontent.com/peter-bread/.dotfiles/refs/heads/main/install
chmod u+x ./install
./install -h
```
Using `wget`:
```bash
wget -q https://raw.githubusercontent.com/peter-bread/.dotfiles/refs/heads/main/install
chmod u+x ./install
./install -h
```
> [!WARNING]
> If the script detects that the repo is out of date, it will pull changes then
> restart itself. When it restarts, it will always use the version in
> `~/.dotfiles`. If you downloaded the script and it fails after the first run,
> be sure to delete it and only use the one in `~/.dotfiles` in future.
>
> See [this issue](https://github.com/peter-bread/.dotfiles/issues/37).
## File Structure
This repository has an intentionally shallow file structure.
The intent is to make navigating to specific config files quicker, then relying
on `install` scripts to create symlinks and handle "real" directory structure.
The top level consists of a few key things:
| Item | Role |
| ----------------- | ------------------------------------------------------------ |
| `install` | Entry point; clones repo, options to do more |
| `MANIFEST.*` | Files containing lists of modules to be installed on each OS |
| `_*` | Repo utilities; _NOT_ modules |
| other directories | Modules containing config files and install scripts |
Each module consists of:
| Item | Role |
| ------------ | ------------------------------------------------------------------- |
| `install` | Script that creates directories and symlinks; can contain any logic |
| `README.md` | Documentation for the module |
| config files | Self-explanatory |
### Modules
There are three types of modules:
- Config
- Data
- Actions
| Module Type | Files | Install | Description |
| ----------- | ----- | ------- | --------------------------------------------------------------------- |
| Config | ✅ | ✅ | Config files for tools that need to be symlinked to correct locations |
| Data | ✅ | ❌ | Files that are used by other modules or scripts |
| Actions | ❌ | ✅ | Perform operations, e.g. creating directories |
Data and Actions are classed as "Special" modules.
Data modules should _NOT_ be included in `MANIFEST` files.
### Special Modules
Most modules are Config modules, however there are some Special modules.
#### Data
[Packages](./packages/) contains files and scripts used to install software. It
can be used by using the `--pkgs` option with the top-level `install` script.
[Env](./env/) provides a unified environment layer that centralises
shell-agnostic environment settings. Currently it defines environment
variables, but it may later include aliases and POSIX-compatible helper
functions for cross-shell consistency.
These scripts are sourced by shell startup files in the `bash` and `zsh`
modules, not executed.
#### Actions
[Dirs](./dirs/) is responsible for creating directories to ensure a consistent
work environment.
## Neovim
My Neovim configuration is in its own repository
[here](https://github.com/peter-bread/peter.nvim).
It can be cloned manually or by using the `--nvim` option with the top-level
`install` script.