update

2026-02-13 09:57:38 +02:00
parent e35f9651c1
commit 1217337fbb
20 changed files with 867 additions and 65 deletions
--- a/example/README.md
+++ b/example/README.md
@@ -0,0 +1,78 @@
+# Example working scenario
+
+This folder contains a complete, practical dotfiles + bootstrap setup that exercises most `flow`
+features.
+
+## What this example shows
+
+- Dotfiles repository layout with `common/` packages and `profiles/work/` overrides
+- Self-hosted `flow` config + manifest in `common/flow/.config/flow/`
+- Bootstrap profiles for Linux (auto PM detection), Ubuntu (`apt`), Fedora (`dnf`), and macOS
+  (`brew`)
+- Bootstrap actions: `requires`, `hostname`, `locale`, `shell`, package install, binary install,
+  `ssh_keygen`, `configs`, and `runcmd`
+- Package name mapping via `package-map` (`apt`/`dnf`/`brew`)
+- Dotfiles repo workflows: `status`, `pull`, `push`, `sync --relink`, and `edit`
+
+## Layout
+
+- `dotfiles-repo/common/flow/.config/flow/config` example `flow` config
+- `dotfiles-repo/common/flow/.config/flow/manifest.yaml` profiles + package map + binaries
+- `dotfiles-repo/common/zsh/.zshrc`, `common/git/.gitconfig`, `common/tmux/.tmux.conf`
+- `dotfiles-repo/common/nvim/.config/nvim/init.lua`
+- `dotfiles-repo/common/bin/.local/bin/flow-hello`
+- `dotfiles-repo/profiles/work/git/.gitconfig` and `profiles/work/zsh/.zshrc` overrides
+
+## Quick start
+
+Use the absolute path to this local example repo:
+
+```bash
+EXAMPLE_REPO="/ABSOLUTE/PATH/TO/flow-cli/example/dotfiles-repo"
+```
+
+Initialize and link dotfiles:
+
+```bash
+flow dotfiles init --repo "$EXAMPLE_REPO"
+flow dotfiles link
+flow dotfiles status
+```
+
+Check repo commands:
+
+```bash
+flow dotfiles repo status
+flow dotfiles repo pull --relink
+flow dotfiles repo push
+```
+
+Edit package or file/path targets:
+
+```bash
+flow dotfiles edit zsh --no-commit
+flow dotfiles edit common/flow/.config/flow/manifest.yaml --no-commit
+```
+
+Inspect bootstrap profiles and package resolution:
+
+```bash
+flow bootstrap list
+flow bootstrap packages --resolved
+flow bootstrap packages --profile fedora-dev --resolved
+flow bootstrap show linux-auto
+```
+
+Run bootstrap in dry-run mode:
+
+```bash
+flow bootstrap run --profile linux-auto --var TARGET_HOSTNAME=devbox --var USER_EMAIL=you@example.com --dry-run
+flow bootstrap run --profile work-linux --var WORK_EMAIL=you@company.com --dry-run
+```
+
+## Manifest notes
+
+- `linux-auto` omits `package-manager` to demonstrate auto-detection.
+- `ubuntu-dev` uses legacy `packages.package` key to show compatibility.
+- `package-map` rewrites logical names like `fd` and `python-dev` per package manager.
+- If mapping is missing for the selected manager, `flow` uses the original package name and warns.
--- a/example/dotfiles-repo/common/bin/.local/bin/flow-hello
+++ b/example/dotfiles-repo/common/bin/.local/bin/flow-hello
@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+
+echo "Hello from flow example dotfiles"
--- a/example/dotfiles-repo/common/flow/.config/flow/config
+++ b/example/dotfiles-repo/common/flow/.config/flow/config
@@ -0,0 +1,15 @@
+[repository]
+dotfiles_url = /ABSOLUTE/PATH/TO/flow-cli/example/dotfiles-repo
+dotfiles_branch = main
+
+[paths]
+projects_dir = ~/projects
+
+[defaults]
+container_registry = registry.example.com
+container_tag = latest
+tmux_session = default
+
+[targets]
+personal = orb personal.orb
+work@ec2 = work.internal ~/.ssh/id_work
--- a/example/dotfiles-repo/common/flow/.config/flow/env.sh
+++ b/example/dotfiles-repo/common/flow/.config/flow/env.sh
@@ -0,0 +1,2 @@
+export FLOW_ENV=example
+export FLOW_EDITOR=vim
--- a/example/dotfiles-repo/common/flow/.config/flow/manifest.yaml
+++ b/example/dotfiles-repo/common/flow/.config/flow/manifest.yaml
@@ -0,0 +1,96 @@
+profiles:
+  linux-auto:
+    os: linux
+    requires: [TARGET_HOSTNAME, USER_EMAIL]
+    hostname: "$TARGET_HOSTNAME"
+    locale: en_US.UTF-8
+    shell: zsh
+    packages:
+      standard: [git, tmux, zsh, fd, ripgrep, python-dev]
+      binary: [neovim, lazygit]
+    ssh_keygen:
+      - type: ed25519
+        filename: id_ed25519
+        comment: "$USER_EMAIL"
+    configs: [flow, zsh, git, tmux, nvim, bin]
+    runcmd:
+      - mkdir -p ~/projects
+      - git config --global user.email "$USER_EMAIL"
+
+  ubuntu-dev:
+    os: linux
+    package-manager: apt
+    packages:
+      package: [git, tmux, zsh, fd, ripgrep, python-dev]
+      binary: [neovim]
+    configs: [flow, zsh, git, tmux]
+
+  fedora-dev:
+    os: linux
+    package-manager: dnf
+    packages:
+      standard: [git, tmux, zsh, fd, ripgrep, python-dev]
+      binary: [neovim]
+    configs: [flow, zsh, git, tmux]
+
+  macos-dev:
+    os: macos
+    package-manager: brew
+    packages:
+      standard: [git, tmux, zsh, fd, ripgrep]
+      cask: [wezterm]
+      binary: [neovim]
+    configs: [flow, zsh, git, nvim]
+
+  work-linux:
+    os: linux
+    package-manager: apt
+    requires: [WORK_EMAIL]
+    packages:
+      standard: [git, tmux, zsh]
+    configs: [git, zsh]
+    runcmd:
+      - git config --global user.email "$WORK_EMAIL"
+
+package-map:
+  fd:
+    apt: fd-find
+    dnf: fd-find
+    brew: fd
+  python-dev:
+    apt: python3-dev
+    dnf: python3-devel
+    brew: python
+  ripgrep:
+    apt: ripgrep
+    dnf: ripgrep
+    brew: ripgrep
+
+binaries:
+  neovim:
+    source: github:neovim/neovim
+    version: "0.10.4"
+    asset-pattern: "nvim-{{os}}-{{arch}}.tar.gz"
+    platform-map:
+      linux-amd64: { os: linux, arch: x86_64 }
+      linux-arm64: { os: linux, arch: arm64 }
+      macos-arm64: { os: macos, arch: arm64 }
+    install-script: |
+      curl -fL "{{downloadUrl}}" -o /tmp/nvim.tar.gz
+      tar -xzf /tmp/nvim.tar.gz -C /tmp
+      mkdir -p ~/.local/bin
+      cp /tmp/nvim-*/bin/nvim ~/.local/bin/nvim
+
+  lazygit:
+    source: github:jesseduffield/lazygit
+    version: "0.44.1"
+    asset-pattern: "lazygit_{{version}}_{{os}}_{{arch}}.tar.gz"
+    platform-map:
+      linux-amd64: { os: Linux, arch: x86_64 }
+      linux-arm64: { os: Linux, arch: arm64 }
+      macos-arm64: { os: Darwin, arch: arm64 }
+    install-script: |
+      curl -fL "{{downloadUrl}}" -o /tmp/lazygit.tar.gz
+      tar -xzf /tmp/lazygit.tar.gz -C /tmp
+      mkdir -p ~/.local/bin
+      cp /tmp/lazygit ~/.local/bin/lazygit
--- a/example/dotfiles-repo/common/git/.gitconfig
+++ b/example/dotfiles-repo/common/git/.gitconfig
@@ -0,0 +1,9 @@
+[user]
+  name = Example User
+  email = example@example.com
+
+[init]
+  defaultBranch = main
+
+[pull]
+  rebase = true
--- a/example/dotfiles-repo/common/nvim/.config/nvim/init.lua
+++ b/example/dotfiles-repo/common/nvim/.config/nvim/init.lua
@@ -0,0 +1,6 @@
+vim.opt.number = true
+vim.opt.relativenumber = true
+vim.opt.expandtab = true
+vim.opt.shiftwidth = 2
+
+vim.g.mapleader = " "
--- a/example/dotfiles-repo/common/tmux/.tmux.conf
+++ b/example/dotfiles-repo/common/tmux/.tmux.conf
@@ -0,0 +1,3 @@
+set -g mouse on
+set -g history-limit 100000
+setw -g mode-keys vi
--- a/example/dotfiles-repo/common/zsh/.zshrc
+++ b/example/dotfiles-repo/common/zsh/.zshrc
@@ -0,0 +1,8 @@
+export EDITOR=vim
+export PATH="$HOME/.local/bin:$PATH"
+
+alias ll='ls -lah'
+
+if [ -f "$HOME/.config/flow/env.sh" ]; then
+  . "$HOME/.config/flow/env.sh"
+fi
--- a/example/dotfiles-repo/profiles/work/git/.gitconfig
+++ b/example/dotfiles-repo/profiles/work/git/.gitconfig
@@ -0,0 +1,6 @@
+[user]
+  name = Example Work User
+  email = work@example.com
+
+[url "git@github.com:work/"]
+  insteadOf = https://github.com/work/
--- a/example/dotfiles-repo/profiles/work/zsh/.zshrc
+++ b/example/dotfiles-repo/profiles/work/zsh/.zshrc
@@ -0,0 +1,7 @@
+export EDITOR=vim
+export PATH="$HOME/.local/bin:$PATH"
+
+alias ll='ls -lah'
+alias gs='git status -sb'
+
+export WORK_MODE=1