dotune 0.1.0

A cross-platform dotfile manager configured with Lua
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

# dotune

A dotfile manager for configs applied on different operating systems simultaneously. Write Lua scripts to decide where your stuff is being linked to

## Example

Say I want to link [Vieb](https://vieb.dev/) configuration:

```sh
~/Repos/dotfiles/
├── .dotune.lua  # <-- linking script
└── web/         # <-- dotfiles source
    └── vieb/
        ├── .viebrc
        └── colors/...
```

```lua
-- Check if Vieb is installed (if you want)
if not (Windows.roaming_app_data / 'Vieb'):exists() then
    return
end

-- Use `Path` primitive instead of strings
local src = Path.here / 'web/vieb'

Dot.link(src / 'colors', Path.home / '.vieb/colors')
-- ^ symlink ~/Repos/dotfiles/web/vieb/colors -> ~/.vieb/colors

Dot.link((src / '.viebrc'):to(Path.home))
-- ^ symlink ~/Repos/dotfiles/web/vieb/.viebrc -> ~/.viebrc

-- Use `include` to run configs in child folders (like require, but relative)
include 'web/qutebrowser'  -- https://github.com/qutebrowser/qutebrowser
```

```sh
# Execute the script
dotune ~/Repos/dotfiles
```

## CLI

```sh
dotune --help     # Show usage and options
dotune            # Apply .dotune.lua in the current directory
dotune <dir>      # Use another repository folder
dotune --dry-run  # Don't apply write operations to the file system
```

## Lua API

### include

```lua
include 'shell'     -- Run shell/.dotune.lua relative to the current script
include 'web/vieb'  -- Nested paths are allowed; absolute paths, . and .. are not
```

### Dot

#### Dot.link

```lua
-- Create a symlink to a file or directory, creating missing parent directories.
-- Sources must be inside the repository; destinations must be outside it.
-- Replaces existing symlinks; errors if a regular file or directory exists.
Dot.link(Path.here / 'config', XDG.config / 'myapp')
```

#### Dot.copy

```lua
-- Copy a file or directory, creating missing parent directories.
-- Sources must be inside the repository; destinations must be outside it.
-- Directories are merged, matching files are overwritten, extra files are kept.
Dot.copy(Path.here / 'defaults', XDG.config / 'otherapp')
```

### Path

```lua
local config = Path.here / 'config.toml'   -- Join; same as Path.here:join('config.toml')

Dot.link(config:to(XDG.config))            -- Passes source and destination, keeping the filename
Dot.link(config, XDG.config / 'app.toml')  -- Choose a different destination name

local renamed = config % 'app.toml'        -- Replace filename; :with_tail('app.toml')
local backup = config * 'bak'              -- Replace extension; :with_extension('bak')
local parent = config.parent               -- Parent path, or nil at the filesystem root
local exists = config:exists()             -- Whether the path exists
local resolved = config:resolve()          -- Absolute path with symlinks resolved, or nil on failure
local text = tostring(config)              -- Convert a Path to a string

local binary = Path.which('vieb')          -- Find an executable on PATH, or return nil
local home = Path.home                     -- User's home directory
local here = Path.here                     -- Current script's directory; alias of Path.script_dir
local script = Path.script                 -- Current .dotune.lua file
local root = Path.root                     -- Filesystem root (e.g. / or C:\)
```

### XDG

```lua
-- Uses XDG environment variables, falling back to these paths under Path.home:
local config = XDG.config  -- XDG_CONFIG_HOME: ~/.config
local data   = XDG.data    -- XDG_DATA_HOME:   ~/.local/share
local state  = XDG.state   -- XDG_STATE_HOME:  ~/.local/state
local cache  = XDG.cache   -- XDG_CACHE_HOME:  ~/.cache
```

### OS

```lua
local config = OS.match {
    windows = Windows.roaming_app_data,
    macos   = Path.home / 'Library/Application Support',
    linux   = XDG.config,
    unix    = XDG.config,
    _       = Path.home / '.config',
}
-- Priority: exact OS, then unix, then _;
-- All keys are optional, but no match is an error
```

### Platform paths

(Some paths are missing, I didn't go through all this)

#### Windows

```lua
local roaming    = Windows.roaming_app_data    -- APPDATA, or ~/AppData/Roaming
local local_data = Windows.local_app_data      -- LOCALAPPDATA, or ~/AppData/Local
local low        = Windows.local_low_app_data  -- ~/AppData/LocalLow
local documents  = Windows.documents           -- ~/Documents
```

#### Mac

```lua
local applications = Mac.applications  -- /Applications
```

## Development

```sh
mise install
cargo build --release
```