yadm

https://github.com/yadm-dev/yadm
Admin
yadm is a Git-based dotfiles manager designed to help users manage their configuration files across...
Tokens:39,735
Snippets:314
Trust Score:5.3
License:GPL-3.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Bootstrap examples: install-free and source shim

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/api-reference/bootstrap-script.md

Two examples: one for install-free bootstrap of a dotfiles repo, and one for sourcing the shim to use remote yadm until installed locally.

```bash
# Install-free bootstrap of a dotfiles repo
curl -L bootstrap.yadm.io | bash -s -- https://github.com/user/dotfiles.git

# Source the shim so the yadm() function uses remote yadm until installed locally
source <(curl -L bootstrap.yadm.io)
yadm clone https://github.com/user/dotfiles.git
```

--------------------------------

### yadm init usage examples

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/api-reference/init-clone.md

Example invocations of yadm init: default work tree, custom work tree with -w, and forcing recreation with -f.

```bash
# Initialize with the default work tree ($HOME)
yadm init

# Initialize with a custom work tree (must exist)
yadm init -w /home/other

# Recreate an existing repository
yadm init -f
```

--------------------------------

### yadm config usage examples

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/api-reference/config-introspect.md

Common usage examples: set `yadm.auto-alt` to false, assign a class to the local repo, and query the current value of `local.class`.

```bash
# Enable/disable automatic alt linking
yadm config yadm.auto-alt false

# Assign this host to a class (stored in the local repo)
yadm config local.class Work

# Query the current value
yadm config local.class
```

--------------------------------

### Jinja template processor example

Source: https://github.com/yadm-dev/yadm/blob/develop/yadm.md

An equivalent template using the Jinja syntax for j2cli or envtpl.

```jinja
{% if YADM_USER == 'harvey' -%}
 config={{YADM_CLASS}}-{{YADM_OS}}
 {% else -%}
 config=dev-whatever
 {% include 'whatever.extra' %}
 {% endif -%}
```

--------------------------------

### Default template processor example

Source: https://github.com/yadm-dev/yadm/blob/develop/yadm.md

A template using the default processor syntax to conditionally set configuration values.

```text
{% if yadm.user == "harvey" %}
 config={{yadm.class}}-{{yadm.os}}
 {% else %}
 config=dev-whatever
 {% include "whatever.extra" %}
 {% endif %}
```

--------------------------------

### yadm enter basic examples

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/api-reference/enter-misc.md

Basic usage of `yadm enter`: without arguments it starts an interactive subshell where git commands operate on the dotfiles repo; with a command it runs that command via `$SHELL -c`.

```bash
yadm enter                     # interactive subshell; git works against the dotfiles repo
yadm enter echo '$GIT_WORK_TREE'   # print the work tree
```

--------------------------------

### Bootstrap example: pin a specific yadm release

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/api-reference/bootstrap-script.md

Shows how to pin a specific yadm release (e.g., v3.5.0) during a piped bootstrap.

```bash
# Pin a specific yadm release during a piped bootstrap
curl -L bootstrap.yadm.io | bash -s -- https://github.com/user/dotfiles.git v3.5.0
```

--------------------------------

### ESH template processor example

Source: https://github.com/yadm-dev/yadm/blob/develop/yadm.md

An equivalent template using the ESH syntax.

```shell
<% if [ "$YADM_USER" = "harvey" ]; then -%>
 config=<%= $YADM_CLASS %>-<%= $YADM_OS %>
 <% else -%>
 config=dev-whatever
 <%+ whatever.extra %>
 <% fi -%>
```

--------------------------------

### Template example with yadm alt

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/api-reference/templates.md

Shows a tracked file with template syntax (whatever##template) and the yadm alt command that creates 'whatever'. Also includes a Jinja-style variant for the j2cli processor.

```bash
# A tracked file   whatever##template
# Content:
#   {% if yadm.user == "harvey" %}
#   config={{yadm.class}}-{{yadm.os}}
#   {% else %}
#   config=dev-whatever
#   {% include "whatever.extra" %}
#   {% endif %}
yadm alt           # creates 'whatever'

# Jinja-style with the j2cli processor (file: whatever##template.j2)
#   {% if YADM_USER == 'harvey' -%}
#   config={{YADM_CLASS}}-{{YADM_OS}}
#   {% else -%}
#   config=dev-whatever
#   {% endif -%}
```

--------------------------------

### Default template processor output examples

Source: https://github.com/yadm-dev/yadm/blob/develop/yadm.md

Expected output for the default template processor based on the user condition.

```text
config=work-Linux
```

```text
config=dev-whatever
 admin=false
```

--------------------------------

### yadm introspect usage examples

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/api-reference/config-introspect.md

Examples of using introspection to retrieve repository paths or iterate over configuration keys.

```bash
YADM_REPO="$(yadm introspect repo)"
for key in $(yadm introspect configs); do echo "$key"; done
```

--------------------------------

### yadm quick tour: init, clone, add, commit, encrypt, decrypt, and alternates

Source: https://github.com/yadm-dev/yadm/blob/develop/README.md

A quick tour of yadm commands covering initialization, cloning, adding and committing files, encrypting and decrypting SSH keys, and creating OS-specific alternate files. The encryption example writes '.ssh/id_rsa' to ~/.config/yadm/encrypt before running yadm encrypt.

```bash
# Initialize a new repository
yadm init

# Clone an existing repository
yadm clone <url>

# Add files/changes
yadm add <important file>
yadm commit

# Encrypt your ssh key
echo '.ssh/id_rsa' > ~/.config/yadm/encrypt
yadm encrypt

# Later, decrypt your ssh key
yadm decrypt

# Create different files for Linux vs MacOS
yadm add path/file.cfg##os.Linux
yadm add path/file.cfg##os.Darwin
```

--------------------------------

### Configure Zsh completion manually

Source: https://github.com/yadm-dev/yadm/blob/develop/completion/README.md

Add the completion/zsh folder to $fpath in .zshrc for manual Zsh installation.

```zsh
fpath=(/path/to/yadm/completion/zsh $fpath)
autoload -U compinit
compinit
```

--------------------------------

### yadm clone usage examples

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/api-reference/init-clone.md

Three example invocations of yadm clone: a standard clone, a forced re-clone with submodules and bootstrap, and a clone that initializes only one submodule while skipping checkout.

```bash
# Standard clone into $HOME
yadm clone https://github.com/user/dotfiles.git

# Force a re-clone, initialize submodules, auto-run bootstrap
yadm clone -f --recursive --bootstrap https://github.com/user/dotfiles.git

# Clone only one submodule, skip checkout
yadm clone --recurse-submodules=vim-config -n https://github.com/user/dotfiles.git
```

--------------------------------

### Example pre_commit hook

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/api-reference/hooks.md

A sample pre_commit hook that prints a message and exits successfully. Place it in $YADM_HOOKS (default ~/.config/yadm/hooks) and make it executable.

```bash
# ~/.config/yadm/hooks/pre_commit — demand a clean index message
#!/bin/bash
echo "About to commit: $YADM_HOOK_COMMAND"
exit 0
```

--------------------------------

### Basic yadm invocation examples

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/api-reference/cli.md

Shows basic yadm usage: git pass-through for 'status', internal command 'config', and global option '--yadm-repo' before the command.

```bash
# git pass-through: 'status' is not an internal command
# → git status on the yadm repo
yadm status

yadm config yadm.auto-alt false   # internal command
yadm --yadm-repo /mnt/repo.git status   # global option before the command
```

--------------------------------

### Query and set yadm configuration with yadm config

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/configuration.md

Shows how to query and set yadm configuration values using the config command. The first command sets yadm.auto-alt to true, the second queries the boolean value of yadm.alt-copy. These are typical usage examples for the yadm config command.

```bash
# Query / set with the config command
yadm config yadm.auto-alt true
yadm config --bool yadm.alt-copy
```

--------------------------------

### Initialize a yadm repository

Source: https://github.com/yadm-dev/yadm/blob/develop/yadm.md

Creates an empty repository for managing dotfiles.

```bash
yadm init
```

--------------------------------

### Handling yadm init failure

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/api-reference/init-clone.md

Shows how to handle the error when yadm init fails because the repo already exists and -f is not provided.

```bash
# Error handling: an existing repo refuses to be clobbered without -f
if ! yadm init 2>&1; then
  echo "Either use -f or inspect the existing repo"
fi
```

--------------------------------

### ESH template processor configuration

Source: https://github.com/yadm-dev/yadm/blob/develop/yadm.md

Example of referencing yadm configuration within an ESH template.

```shell
<% yadm config mysection.myconfig %>
```

--------------------------------

### Configure and encrypt with yadm encrypt and decrypt

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/api-reference/encryption.md

Sets up the encrypt file with a path to encrypt, then runs yadm encrypt with a symmetric GPG passphrase prompt. Later, on another machine, yadm decrypt restores the files and yadm decrypt -l previews the archive contents.

```bash
# Configure and encrypt
echo '.ssh/id_rsa' > ~/.config/yadm/encrypt
yadm encrypt                       # prompts for a passphrase (symmetric gpg)
yadm add ~/.local/share/yadm/archive
yadm commit

# Later, on another machine
yadm decrypt
yadm decrypt -l                    # preview archive contents
```

--------------------------------

### Disable alternates via yadm config

Source: https://github.com/yadm-dev/yadm/blob/develop/yadm.md

Example command to disable automatic alternate file creation.

```bash
yadm config yadm.auto-alt false
```

--------------------------------

### Upgrade command sequence with review and commit

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/api-reference/upgrade.md

Run `yadm upgrade` to migrate, then review staged renames and commit the changes.

```bash
yadm upgrade
yadm status      # review staged renames of tracked files
yadm commit      # commit the relocation changes
```

--------------------------------

### yadm config

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/api-reference/config-introspect.md

Documentation for the `yadm config` command, including its parameters, routing rule, side effects, and examples.

```APIDOC
## `yadm config [name] [value]`

### Description
Reads or writes yadm configuration values. With no arguments, prints the full list of supported key names and a pointer to the man page. With a `name` and optional `value`, reads or sets the configuration key.

### Method
CLI command

### Endpoint
`yadm config [name] [value]`

### Parameters
- **name** (string) - Optional - A config key, e.g. `yadm.auto-alt` or `local.class`.
- **value** (string) - Optional - Value to set. If omitted, the current value is read. Any extra arguments (including `--add`, `--unset`, `--bool`, `-e`) are forwarded verbatim to `git config`.

### Routing Rule
If any argument matches `^local\.(class|arch|os|hostname|user|distro|distro-family)$`, the command is executed against the repository config (`git config "$@"` with `GIT_DIR` exported). Otherwise, it is executed against the yadm config file via `git config --file="<YADM_CONFIG>"`.

### Side Effects
- Every write sets `CHANGES_POSSIBLE=1`, so `auto_alt`/`auto_perms` run afterward.
- The parent directory of `$YADM_CONFIG` is created on demand.
- `local.*` writes require an existing repo; otherwise an error is raised.

### Examples
```bash
# Enable/disable automatic alt linking
yadm config yadm.auto-alt false

# Assign this host to a class (stored in the local repo)
yadm config local.class Work

# Query the current value
yadm config local.class
```

```bash
# Error handling: the config file may be edited but paths are validated
yadm config yadm.alt-copy true
if [ "$(yadm config --bool yadm.alt-copy)" = "true" ]; then
  echo "alternates will be copied"
fi
```
```

--------------------------------

### Seed pattern with yadm config and yadm alt

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/api-reference/templates.md

Demonstrates the seed pattern: process once, then leave the produced file alone. Uses yadm config local.class Work, creates a seed file, and runs yadm alt to render it on first run.

```bash
# Seed pattern: process once, then leave the produced file alone
yadm config local.class Work
echo '<% if [ "$YADM_USER" = "harvey" ]; then -%>hi<% fi %>' > ~/.zshrc##seed.esh
yadm alt            # first run: renders ~/.zshrc; later runs skip it
```

--------------------------------

### init() function source

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/api-reference/init-clone.md

The init() function from yadm:1214. It aborts with an error if the repo already exists unless FORCE is set, then runs git init --shared=0600 --bare, calls configure_repo(), and sets CHANGES_POSSIBLE=1.

```bash
function init() {
  # safety check, don't attempt to init when the repo is already present
  [ -d "$YADM_REPO" ] && [ -z "$FORCE" ] &&
    error_out "Git repo already exists. [$YADM_REPO]\nUse '-f' if you want to force it to be overwritten."
  ...
  "$GIT_PROGRAM" init --shared=0600 --bare "$(mixed_path "$YADM_REPO")" "$@"
  configure_repo
  CHANGES_POSSIBLE=1
}
```

--------------------------------

### Source yadm Bash completion

Source: https://github.com/yadm-dev/yadm/blob/develop/completion/README.md

Add this to your bashrc after copying the completion script locally for manual Bash installation.

```bash
[ -f /path/to/yadm/completion/bash/yadm ] && source /path/to/yadm/completion/bash/yadm
```

--------------------------------

### Assign multiple classes with yadm config local.class

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/configuration.md

Demonstrates assigning multiple classes to the local repository using the local.class key. The first command sets the class to Work, and the second adds Laptop as an additional class. These values are stored locally in the repo.

```bash
# Assign multiple classes (stored locally in the repo)
yadm config local.class Work
yadm config --add local.class Laptop
```

--------------------------------

### Override yadm repository directory with an alias

Source: https://github.com/yadm-dev/yadm/blob/develop/yadm.md

Example of creating an alias for the yadm command to permanently override the repository directory path.

```bash
alias yadm='yadm --yadm-repo /alternate/path/to/repo'
```

--------------------------------

### yadm gitconfig usage examples

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/api-reference/config-introspect.md

Use gitconfig as an escape hatch for settings reserved by yadm, such as modifying git configuration directly.

```bash
yadm gitconfig --unset status.showUntrackedFiles
yadm gitconfig user.email "you@example.com"
```

--------------------------------

### Comment about parsing YADM_HOOK_FULL_COMMAND

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/api-reference/hooks.md

A comment-only example indicating that escaped spaces in YADM_HOOK_FULL_COMMAND must be recovered before tokenizing the parameter list. See contrib/hooks/parsing_full_command_example/pre_log.

```bash
# Parse YADM_HOOK_FULL_COMMAND (see contrib/hooks/parsing_full_command_example/pre_log)
# Escaped spaces must be recovered before tokenizing the parameter list.
```

--------------------------------

### Configure Emacs TRAMP for yadm

Source: https://github.com/yadm-dev/yadm/blob/develop/yadm.md

Add this configuration to your Emacs setup to enable TRAMP support for yadm, then use magit-status with the specified path.

```elisp
(add-to-list 'tramp-methods
     '("yadm"
       (tramp-login-program "yadm")
       (tramp-login-args (("enter")))
       (tramp-login-env (("SHELL") ("/bin/sh")))
       (tramp-remote-shell "/bin/sh")
       (tramp-remote-shell-args ("-c"))))
```

```elisp
(magit-status "/yadm::")
```

--------------------------------

### yadm help function

Source: https://github.com/yadm-dev/yadm/blob/develop/_autodocs/api-reference/enter-misc.md

Prints command summary and resolved file paths with $HOME abbreviated, then exits with code 1 (post hooks run).

```bash
function help() {
  readonly config="${YADM_CONFIG/$HOME/\$HOME}"
  ...
  printf '%s\n' "$msg"
  exit_with_hook 1
}
```
Tokens:
Raw