diff --git a/CHANGELOG.md b/CHANGELOG.md index f0c9cc9..a51fc4e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,37 @@ Versions increment by one patch step (0.0.1) per release. --- +## [1.0.7] - 2026-06-05 + +### Added + +- Starship prompt across all three platforms: `mac/topics/59-starship.zsh`, + `linux/topics/59-starship.sh`, `windows/topics/59-starship.ps1` — each + contains the single platform-specific init line. +- `shared/starship.toml`: one config file for all three platforms covering git, + all languages in the 59 topic files (Python, Node, Go, Rust, Java/Kotlin/Scala, + PHP, Ruby, .NET, Docker, Lua, Zig, Swift, Elixir), and command duration. + Cloud modules (AWS, GCloud, Azure) disabled for startup performance. +- `journal/009-starship-prompt.md`: reasoning behind adding Starship, module + choices, the shared/ approach, and how to disable it. + +### Changed + +- `shared/README.md`: updated to list `starship.toml` and explain the shared + config pattern. +- `NOTICE`: updated to mention `shared/starship.toml` and the symlink step. +- `guides/mac.md`, `guides/linux.md`, `guides/windows.md`: topic count updated + from 58 to 59; Starship topic file and symlink noted in loader section. +- `guides/new-device.md`: Starship setup steps added for all three platforms + (install + symlink); added to Contents; dedicated section before Mirror setup. +- `documentation.md`: architecture updated to 59 topic files; Starship section + added with full module table and disable instructions; "next available number" + note updated from 59 to 60. +- `will-do/new-device-setup.md`: Starship step expanded with platform-specific + install and symlink commands. + +--- + ## [1.0.6] - 2026-06-05 ### Added diff --git a/NOTICE b/NOTICE index 7a99faa..1ed8f4d 100644 --- a/NOTICE +++ b/NOTICE @@ -9,11 +9,12 @@ matches your machine - do not mix files across platforms. linux/ Linux only (bash, apt/pacman, Linux-specific paths and tools) windows/ Windows only (PowerShell, winget/choco, Windows-specific paths) -The shared/ folder contains files used by all three platforms. +The shared/ folder contains files used by all three platforms, including +starship.toml — the Starship prompt config. Symlink it to ~/.config/starship.toml +on each device (see the Starship section in will-do/new-device-setup.md). The scripts/ folder contains utility scripts that run from any platform. The hooks/ folder contains git hooks that can be installed manually. - What you must change before using these dotfiles ------------------------------------------------- @@ -46,6 +47,11 @@ What you must change before using these dotfiles to match the version on your machine, or remove it and rely on the dynamic finder function. +7. Starship prompt in 59-starship + The 59-starship topic file is already written for all three platforms. + After cloning, symlink shared/starship.toml to ~/.config/starship.toml and + install Starship for your platform. See will-do/new-device-setup.md for the + exact commands per platform. API tokens and secrets - never commit these ------------------------------------------- @@ -65,7 +71,6 @@ The recommended approach is to keep all tokens in a file at ~/.mirror_tokens (chmod 600) and source it from your profile. That file is listed in .gitignore and must never be committed. - Platform-specific tools mentioned in these files ------------------------------------------------- @@ -83,10 +88,12 @@ Some tools appear only on one platform because they have no equivalent elsewhere /opt/resolve/bin/resolve for DaVinci Resolve (55-media.sh) /dev/ttyUSB* and /dev/ttyACM* for serial devices (49-eda.sh) + All platforms: shared/starship.toml covers all languages and tools across + the 59 topic files. One symlink per device is all that is needed. + If a command listed in cmds() does not exist on your platform, it will simply not be defined - the loader will source the file without error. - Licence ------- diff --git a/documentation.md b/documentation.md index 1b2fda7..43d914f 100644 --- a/documentation.md +++ b/documentation.md @@ -70,7 +70,7 @@ Detailed technical reference for this dotfiles repo. This covers how the loader ## Architecture -The profile is split across 58 numbered topic files rather than kept in a single monolithic profile. I did this because a single file past a few hundred lines becomes hard to navigate, and topic files make it easy to find, add or remove a section without touching anything else. +The profile is split across 59 numbered topic files rather than kept in a single monolithic profile. I did this because a single file past a few hundred lines becomes hard to navigate, and topic files make it easy to find, add or remove a section without touching anything else. ``` dotfiles/ @@ -79,10 +79,12 @@ dotfiles/ - mac/topics/02-colours.zsh second topic file - ... - mac/topics/58-productivity.zsh +- mac/topics/59-starship.zsh Starship prompt init - linux/bashrc loader for Linux and WSL2 (bash) -- linux/topics/*.sh same 58 topics, bash syntax +- linux/topics/*.sh same 59 topics, bash syntax - windows/Microsoft.PowerShell_profile.ps1 loader for Windows (PowerShell) -- windows/topics/*.ps1 same 58 topics, PowerShell syntax +- windows/topics/*.ps1 same 59 topics, PowerShell syntax +- shared/starship.toml Starship prompt config — one file for all three platforms ``` --- @@ -1359,11 +1361,50 @@ Defined in `58-productivity` on all platforms. --- +## Starship prompt + +Defined in `59-starship` on all platforms. Config in `shared/starship.toml`. + +Starship replaces the shell's default prompt line (`%` / `$`) with a dynamic one that +re-evaluates on every Enter press. Only modules relevant to the current directory appear — +git info only shows inside git repos, language versions only inside matching projects. + +| What you see | When it appears | +| --- | --- | +| Directory (bold blue, 3 segments) | Always | +| Branch + git status | Inside any git repo | +| Python version | `.py` file, `pyproject.toml`, `requirements.txt`, or `.python-version` present | +| Node version | `package.json` present | +| Go version | `go.mod` or `.go` files present | +| Rust version | `Cargo.toml` or `.rs` files present | +| Java/Kotlin/Scala | `.java`, `.kt`, `.kts`, or `.scala` files present | +| PHP version | `.php` files present | +| Ruby version | `.rb` files or `Gemfile` present | +| .NET version | `.cs`, `.csproj`, or `.fsproj` files present | +| Docker context | `Dockerfile` or `docker-compose.yml` present | +| Lua version | `.lua` files present | +| Zig version | `.zig` files present | +| Swift version | `.swift` files present | +| Elixir version | `.ex`, `.exs`, or `mix.exs` present | +| Haskell version | `stack.yaml`, `.cabal`, or `.hs` files present | +| Deno version | `deno.json`, `deno.jsonc`, or `deno.lock` present | +| Bun version | `bun.lockb` present | +| Dart/Flutter version | `pubspec.yaml` present | +| C/C++ | `.c`, `.cpp`, `.h`, or `.hpp` files present | +| Command duration | Any command that took longer than 2 seconds | + +To disable Starship entirely: comment out the `eval` line in `59-starship.zsh` (or `.sh` / `.ps1`) and reload. +To hide a specific module: add `disabled = true` under its section in `shared/starship.toml`. + +The `starship.toml` is shared — editing it once updates the prompt on all three platforms on the next shell open. + +--- + ## Extending the profile To add a new group of aliases: -1. Create a new file in the relevant `topics/` folder with the next available number, e.g. `59-mytopic.zsh` (macOS), `59-mytopic.sh` (Linux) or `59-mytopic.ps1` (Windows). +1. Create a new file in the relevant `topics/` folder with the next available number, e.g. `60-mytopic.zsh` (macOS), `60-mytopic.sh` (Linux) or `60-mytopic.ps1` (Windows). (`59` is taken by Starship.) 2. Add your aliases and functions to the file. 3. Reload the profile: `reload-profile`. 4. Run `cmds` to verify the new commands appear. If you want them listed there too, add a section to `06-functions` under `cmds()`. diff --git a/guides/linux.md b/guides/linux.md index e88f0f4..e4d3d12 100644 --- a/guides/linux.md +++ b/guides/linux.md @@ -80,7 +80,9 @@ for f in "$DOTFILES/linux/topics"/[0-9]*.sh; do done ``` -Files load from `01-path.sh` to `58-productivity.sh`. A higher-numbered file overrides an alias from a lower-numbered one if they share a name. See [linux/topics/README.md](../linux/topics/README.md) for the full listing. +Files load from `01-path.sh` to `59-starship.sh`. A higher-numbered file overrides an alias from a lower-numbered one if they share a name. See [linux/topics/README.md](../linux/topics/README.md) for the full listing. + +`59-starship.sh` initialises the Starship prompt. The config lives in [shared/starship.toml](../shared/starship.toml) — one file shared across all three platforms. Symlink it to `~/.config/starship.toml` on each device. --- diff --git a/guides/mac.md b/guides/mac.md index 4bb5593..3e29995 100644 --- a/guides/mac.md +++ b/guides/mac.md @@ -69,9 +69,11 @@ for f in "$DOTFILES/mac/topics"/[0-9]*.zsh; do done ``` -Files are loaded from `01-path.zsh` to `58-productivity.zsh`. A higher-numbered file overrides an alias from a lower-numbered one if they share a name. See [mac/topics/README.md](../mac/topics/README.md) for the full listing of all topic files. +Files are loaded from `01-path.zsh` to `59-starship.zsh`. A higher-numbered file overrides an alias from a lower-numbered one if they share a name. See [mac/topics/README.md](../mac/topics/README.md) for the full listing of all topic files. -To add a new group of aliases, create a new file (e.g. `59-mytopic.zsh`) in `mac/topics/`. It is picked up automatically at the next `reload-profile`. No changes to `zshrc` needed. +`59-starship.zsh` initialises the Starship prompt. The config lives in [shared/starship.toml](../shared/starship.toml) — one file shared across all three platforms. Symlink it to `~/.config/starship.toml` on each device. + +To add a new group of aliases, create a new file (e.g. `60-mytopic.zsh`) in `mac/topics/`. It is picked up automatically at the next `reload-profile`. No changes to `zshrc` needed. --- diff --git a/guides/new-device.md b/guides/new-device.md index 43d3314..eb1d32e 100644 --- a/guides/new-device.md +++ b/guides/new-device.md @@ -10,6 +10,7 @@ Step-by-step walkthrough for setting up these dotfiles on a brand new machine. F - [Linux (Ubuntu / Debian)](#linux-ubuntu--debian) - [WSL2 on Windows](#wsl2-on-windows) - [Windows (native PowerShell)](#windows-native-powershell) +- [Starship prompt (all platforms)](#starship-prompt-all-platforms) - [Mirror setup (all platforms)](#mirror-setup-all-platforms) --- @@ -67,7 +68,19 @@ Download from [code.visualstudio.com](https://code.visualstudio.com). After inst Press `Cmd+Shift+P` in VS Code, type "Shell Command: Install 'code' command in PATH" and run it. -### 7 - Install language runtimes +### 7 - Set up the Starship prompt + +`59-starship.zsh` is already in the profile and will be sourced automatically. You just need to install Starship and symlink the shared config: + +```bash +brew install starship +mkdir -p ~/.config +ln -sf /path/to/your/projects/dotfiles/shared/starship.toml ~/.config/starship.toml +``` + +Open a new terminal tab. The prompt will show your current directory, git branch, and language versions automatically. + +### 8 - Install language runtimes Install whichever runtimes you need: @@ -129,7 +142,19 @@ sudo snap install --classic code Or download the `.deb` package from [code.visualstudio.com](https://code.visualstudio.com). -### 6 - Install language runtimes +### 6 - Set up the Starship prompt + +`59-starship.sh` is already in the profile and will be sourced automatically. You just need to install Starship and symlink the shared config: + +```bash +curl -sS https://starship.rs/install.sh | sh +mkdir -p ~/.config +ln -sf /path/to/your/projects/dotfiles/shared/starship.toml ~/.config/starship.toml +``` + +Open a new terminal tab. The prompt will show your current directory, git branch, and language versions automatically. + +### 7 - Install language runtimes ```bash sudo apt install -y python3 python3-pip golang nodejs npm @@ -210,7 +235,22 @@ Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser > [!NOTE] > The profile uses `C:\dev` as a convention for the base dev folder. Review [windows/topics/03-navigation.ps1](../windows/topics/03-navigation.ps1) and adjust the directory shortcuts to match your own folder layout before applying. -### 5 - Install language runtimes +### 5 - Set up the Starship prompt + +`59-starship.ps1` is already in the profile and will be sourced automatically. You just need to install Starship and symlink the shared config: + +```powershell +winget install Starship.Starship +New-Item -ItemType Directory -Force -Path "$HOME\.config" +New-Item -ItemType SymbolicLink -Path "$HOME\.config\starship.toml" -Target "C:\path\to\your\projects\dotfiles\shared\starship.toml" +``` + +> [!NOTE] +> Creating a symlink on Windows requires either running PowerShell as Administrator or enabling Developer Mode in Settings → System → For developers. + +Open a new terminal tab. The prompt will show your current directory, git branch, and language versions automatically. + +### 6 - Install language runtimes ```powershell winget install OpenJS.NodeJS Python.Python.3 GoLang.Go Rustlang.Rustup @@ -218,6 +258,44 @@ winget install OpenJS.NodeJS Python.Python.3 GoLang.Go Rustlang.Rustup --- +## Starship prompt (all platforms) + +The `59-starship` topic file is already written for all three platforms and sourced automatically +when the profile loads. All that is needed on a new device is to install Starship and symlink the +shared config. The config lives in `shared/starship.toml` — one file, identical across all devices. +Never create platform-specific versions; edit the shared file and it updates everywhere. + +### macOS + +```bash +brew install starship +mkdir -p ~/.config +ln -sf /path/to/your/projects/dotfiles/shared/starship.toml ~/.config/starship.toml +``` + +### Linux / WSL2 + +```bash +curl -sS https://starship.rs/install.sh | sh +mkdir -p ~/.config +ln -sf /path/to/your/projects/dotfiles/shared/starship.toml ~/.config/starship.toml +``` + +### Windows (native PowerShell) + +```powershell +winget install Starship.Starship +New-Item -ItemType Directory -Force -Path "$HOME\.config" +New-Item -ItemType SymbolicLink -Path "$HOME\.config\starship.toml" -Target "C:\path\to\your\projects\dotfiles\shared\starship.toml" +``` + +> [!NOTE] +> Creating a symlink on Windows requires either running PowerShell as Administrator or enabling Developer Mode in Settings → System → For developers. + +Open a new terminal tab — the prompt updates immediately. See [shared/starship.toml](../shared/starship.toml) to add or disable modules. + +--- + ## Mirror setup (all platforms) ### 1 - Create the token file diff --git a/guides/windows.md b/guides/windows.md index c39c52a..f6e7a3d 100644 --- a/guides/windows.md +++ b/guides/windows.md @@ -87,7 +87,9 @@ Get-ChildItem "$PSScriptRoot\topics\[0-9]*.ps1" | Sort-Object Name | ForEach-Obj } ``` -Files load from `01-path.ps1` to `58-productivity.ps1`. A later-numbered file overrides a function from an earlier one if they share a name. See [windows/topics/README.md](../windows/topics/README.md) for the full listing. +Files load from `01-path.ps1` to `59-starship.ps1`. A later-numbered file overrides a function from an earlier one if they share a name. See [windows/topics/README.md](../windows/topics/README.md) for the full listing. + +`59-starship.ps1` initialises the Starship prompt. The config lives in [shared/starship.toml](../shared/starship.toml) — one file shared across all three platforms. Symlink it to `~/.config/starship.toml` on each device. --- diff --git a/journal/009-starship-prompt.md b/journal/009-starship-prompt.md new file mode 100644 index 0000000..dbd1ed5 --- /dev/null +++ b/journal/009-starship-prompt.md @@ -0,0 +1,104 @@ +# 009 - Starship prompt + +**Date:** June 2026 +**Status:** Complete + +--- + +## Why I added it + +My prompt before Starship was a plain `%` on macOS and `$` on Linux. Every time I opened a +terminal tab I had no idea which branch I was on, whether there were uncommitted changes, or +what folder I was in without running `pwd`. I was running `gs` constantly just to orient myself. + +The other reason is consistency. My whole dotfiles setup is built around the rule that muscle +memory should carry identically across Mac, Linux and Windows. The prompt was the one place +where that broke down — zsh, bash and PowerShell each have their own prompt syntax and there +is no way to write one prompt string that works on all three shells. + +Starship solves both problems. One `starship.toml` config file covers all three platforms. The +init line (`eval "$(starship init zsh)"` etc.) goes in the platform-specific `59-starship` topic +file, but everything about the actual prompt appearance lives in `shared/starship.toml`. Changing +the config once updates the prompt on every device. + +--- + +## Why topic file 59 + +The existing 58 topic files run from `01-path` to `58-productivity`. Starship must be initialised +last because it hooks into the shell prompt, and the prompt should only be set after all aliases, +functions and environment variables from the other 58 files are already loaded. Putting it at 59 +guarantees it runs last in the glob sort order. + +--- + +## The shared/ folder + +Before this, `shared/` only contained markdown reference docs. `starship.toml` is the first +actual config file in `shared/` — a real runtime dependency, not just documentation. The README +in `shared/` was updated to reflect this. + +The symlink approach was chosen over copying the file to each device because: + +- A copy drifts: if I change the config I have to remember to recopy to every device +- A symlink always reads from the repo — pull once, all devices update on next shell open +- It follows the same pattern as the rest of the dotfiles (edit in repo, reload profile) + +--- + +## Module choices + +Starship has modules for dozens of languages and tools. I enabled only the ones that match +the 59 topic files in this repo: + +| Module | Topic file | +| --- | --- | +| `git_branch`, `git_status` | 04-git | +| `python` | 26-python | +| `nodejs` | 27-web | +| `golang` | 34-go | +| `rust` | 35-rust | +| `dotnet` | 36-dotnet | +| `java` (covers Kotlin/Scala) | 37-kotlin, 38-scala, 42-java | +| `php` | 30-php | +| `ruby` | 29-ruby | +| `lua` | 33-lua | +| `zig` | 47-zig | +| `swift` | 41-swift | +| `elixir` | 32-elixir | +| `docker_context` | 22-docker | +| `cmd_duration` | all — shows if any command takes over 2s | + +Cloud modules (AWS, GCloud, Azure) are explicitly disabled because I do not use them and +they add latency to every prompt render by querying config files. + +--- + +## Disabling it + +To disable Starship entirely: comment out the single `eval` line in `59-starship.zsh` (or +`.sh` / `.ps1`) and run `reload-profile`. The rest of the profile is unaffected. + +To hide a specific module: add `disabled = true` under its section in `shared/starship.toml`. +The change takes effect on the next shell open on every device. + +--- + +## What the prompt looks like + +In a git repo with uncommitted changes inside a Go project: + +``` +dotfiles main * via 🐹 v1.22 +> +``` + +In an ordinary folder with no git, no recognised language: + +``` +~/documents +> +``` + +The prompt line and the input line are separate. The `>` is where you type. Directory and +context always appear on the line above it. diff --git a/linux/topics/59-starship.sh b/linux/topics/59-starship.sh new file mode 100644 index 0000000..b6ee6e8 --- /dev/null +++ b/linux/topics/59-starship.sh @@ -0,0 +1 @@ +eval "$(starship init bash)" diff --git a/mac/topics/59-starship.zsh b/mac/topics/59-starship.zsh new file mode 100644 index 0000000..af75929 --- /dev/null +++ b/mac/topics/59-starship.zsh @@ -0,0 +1 @@ +eval "$(starship init zsh)" diff --git a/shared/README.md b/shared/README.md index efa46e9..02eccc8 100644 --- a/shared/README.md +++ b/shared/README.md @@ -1,10 +1,18 @@ # shared/ -Platform-agnostic reference documents that apply across macOS, Linux and Windows. +Platform-agnostic files that apply identically across macOS, Linux and Windows. +Anything in here is used by all three platforms — there are no platform-specific versions. ## Files | File | Contents | | --- | --- | +| [`starship.toml`](starship.toml) | Starship prompt config — one file for all three platforms. Symlink to `~/.config/starship.toml` on each device. Covers git, all languages in the 59 topic files, and command duration. | | [`python-venv-guide.md`](python-venv-guide.md) | Per-project virtual environment strategy: why I use venv over conda, how to create, activate and freeze dependencies, and how the `venv` and `activate` aliases work | | [`shell-profile-guide.md`](shell-profile-guide.md) | Combined alias and colour reference covering commands that behave identically across all three platforms | + +## How the shared config works + +Each platform's `59-starship` topic file contains a single init line for its shell. +The `starship.toml` config is identical on all three — only the init line differs per shell. +To change the prompt appearance, edit `starship.toml` once and it updates everywhere on the next shell open. diff --git a/shared/starship.toml b/shared/starship.toml new file mode 100644 index 0000000..734f30e --- /dev/null +++ b/shared/starship.toml @@ -0,0 +1,145 @@ +# Starship prompt config — shared across Mac (zsh), Linux (bash), and Windows (PowerShell) +# Symlink to ~/.config/starship.toml on each device. +# One file, all 3 platforms, no platform-specific versions needed. +# +# To disable Starship entirely: comment out the eval line in 59-starship.zsh / .sh / .ps1 +# To hide a specific module: add disabled = true under its [section] below + +# Disable cloud modules I don't use so startup stays fast +[aws] +disabled = true + +[gcloud] +disabled = true + +[azure] +disabled = true + +# Prompt character — green on success, red on failure +[character] +success_symbol = "[>](bold green)" +error_symbol = "[>](bold red)" + +# Git branch +[git_branch] +symbol = " " +style = "bold cyan" + +# Git status — ASCII so it works without a Nerd Font +[git_status] +conflicted = "!" +ahead = "^${count}" +behind = "v${count}" +diverged = "^${ahead_count}v${behind_count}" +modified = "*" +staged = "+" +untracked = "?" +deleted = "x" +style = "bold yellow" + +# Directory — shorten to 3 segments, collapse at repo root +[directory] +truncation_length = 3 +truncate_to_repo = true +style = "bold blue" + +# Python — shows venv name when inside a Python project +[python] +detect_extensions = ["py"] +detect_files = ["pyproject.toml", "requirements.txt", "setup.py", ".python-version"] +style = "bold yellow" + +# Node — only shows when package.json is present +[nodejs] +detect_files = ["package.json"] +style = "bold green" + +# Go +[golang] +detect_extensions = ["go"] +detect_files = ["go.mod"] +style = "bold cyan" + +# Rust +[rust] +detect_extensions = ["rs"] +detect_files = ["Cargo.toml"] +style = "bold red" + +# Java / Kotlin / Scala +[java] +detect_extensions = ["java", "kt", "kts", "scala"] +style = "bold red" + +# PHP +[php] +detect_extensions = ["php"] +style = "bold purple" + +# Ruby +[ruby] +detect_extensions = ["rb"] +detect_files = ["Gemfile"] +style = "bold red" + +# .NET / C# +[dotnet] +detect_extensions = ["cs", "csproj", "fsproj"] +style = "bold blue" + +# Docker — shows when a Dockerfile or compose file is present +[docker_context] +detect_files = ["docker-compose.yml", "docker-compose.yaml", "Dockerfile"] +style = "bold blue" + +# Lua +[lua] +detect_extensions = ["lua"] +style = "bold blue" + +# Zig +[zig] +detect_extensions = ["zig"] +style = "bold yellow" + +# Swift +[swift] +detect_extensions = ["swift"] +style = "bold orange" + +# Elixir +[elixir] +detect_extensions = ["ex", "exs"] +detect_files = ["mix.exs"] +style = "bold purple" + +# Haskell — only shows when stack.yaml or .cabal files are present +[haskell] +detect_files = ["stack.yaml", "cabal.project"] +detect_extensions = ["hs", "cabal"] +style = "bold purple" + +# Deno — only shows when deno.json or deno.lock is present +[deno] +detect_files = ["deno.json", "deno.jsonc", "deno.lock"] +style = "bold green" + +# Bun — only shows when bun.lockb is present +[bun] +detect_files = ["bun.lockb"] +style = "bold yellow" + +# Dart / Flutter — only shows when pubspec.yaml is present +[dart] +detect_files = ["pubspec.yaml"] +style = "bold blue" + +# C / C++ — only shows when .c, .cpp, .h files are present +[c] +detect_extensions = ["c", "cpp", "h", "hpp"] +style = "bold blue" + +# Command duration — shows how long the last command took if over 2s +[cmd_duration] +min_time = 2_000 +style = "bold yellow" diff --git a/windows/topics/59-starship.ps1 b/windows/topics/59-starship.ps1 new file mode 100644 index 0000000..9deeb1d --- /dev/null +++ b/windows/topics/59-starship.ps1 @@ -0,0 +1 @@ +Invoke-Expression (&starship init powershell)