From 5e4d5d275021309588a141f20677a55315483233 Mon Sep 17 00:00:00 2001 From: shelton louis Date: Tue, 1 Oct 2024 15:05:50 -0400 Subject: [PATCH] yadm: add pages (#13920) Co-authored-by: Sebastiaan Speck <12570668+sebastiaanspeck@users.noreply.github.com> Co-authored-by: Wiktor Perskawiec --- pages/common/yadm-alt.md | 9 +++++++++ pages/common/yadm-bootstrap.md | 9 +++++++++ pages/common/yadm-clone.md | 30 ++++++++++++++++++++++++++++++ pages/common/yadm-config.md | 20 ++++++++++++++++++++ pages/common/yadm-decrypt.md | 9 +++++++++ pages/common/yadm-encrypt.md | 13 +++++++++++++ pages/common/yadm-enter.md | 13 +++++++++++++ pages/common/yadm-git-crypt.md | 21 +++++++++++++++++++++ pages/common/yadm-gitconfig.md | 21 +++++++++++++++++++++ pages/common/yadm-init.md | 17 +++++++++++++++++ pages/common/yadm-introsepct.md | 21 +++++++++++++++++++++ pages/common/yadm-list.md | 12 ++++++++++++ pages/common/yadm-perms.md | 9 +++++++++ pages/common/yadm-transcrypt.md | 26 ++++++++++++++++++++++++++ pages/common/yadm-upgrade.md | 13 +++++++++++++ pages/common/yadm.md | 33 +++++++++++++++++++++++++++++++++ 16 files changed, 276 insertions(+) create mode 100755 pages/common/yadm-alt.md create mode 100755 pages/common/yadm-bootstrap.md create mode 100755 pages/common/yadm-clone.md create mode 100755 pages/common/yadm-config.md create mode 100755 pages/common/yadm-decrypt.md create mode 100755 pages/common/yadm-encrypt.md create mode 100755 pages/common/yadm-enter.md create mode 100755 pages/common/yadm-git-crypt.md create mode 100755 pages/common/yadm-gitconfig.md create mode 100755 pages/common/yadm-init.md create mode 100755 pages/common/yadm-introsepct.md create mode 100755 pages/common/yadm-list.md create mode 100755 pages/common/yadm-perms.md create mode 100755 pages/common/yadm-transcrypt.md create mode 100755 pages/common/yadm-upgrade.md create mode 100755 pages/common/yadm.md diff --git a/pages/common/yadm-alt.md b/pages/common/yadm-alt.md new file mode 100755 index 000000000..69ede9d2c --- /dev/null +++ b/pages/common/yadm-alt.md @@ -0,0 +1,9 @@ +# yadm-alt + +> Create symbolic links and process templates for any managed files. +> Learn more about templates: . +> More information: . + +- Create symbolic links between alternate files manually: + +`yadm alt` diff --git a/pages/common/yadm-bootstrap.md b/pages/common/yadm-bootstrap.md new file mode 100755 index 000000000..a075ea72a --- /dev/null +++ b/pages/common/yadm-bootstrap.md @@ -0,0 +1,9 @@ +# yadm-bootstrap + +> Execute Yadm's bootstrap file. +> This file should be created in `$HOME/.config/yadm/bootstrap`. +> More information: . + +- Execute bootstrap executable: + +`yadm bootstrap` diff --git a/pages/common/yadm-clone.md b/pages/common/yadm-clone.md new file mode 100755 index 000000000..0273876f7 --- /dev/null +++ b/pages/common/yadm-clone.md @@ -0,0 +1,30 @@ +# yadm-clone + +> Works just like `git clone`. In addition you can pass extra flags to configure your repository. +> If there is a bootstrap file in the repository, you will be prompted to execute it. +> See also: `git clone`. +> More information: . + +- Clone an existing repository: + +`yadm clone {{remote_repository_location}}` + +- Clone an existing repository, then execute the bootstrap file: + +`yadm clone {{remote_repository_location}} --bootstrap` + +- Clone an existing repository and after cloning, do not execute the bootstrap file: + +`yadm clone {{remote_repository_location}} --no-bootstrap` + +- Change the worktree that `yadm` will use during cloning: + +`yadm clone {{remote_repository_location}} --w {{worktree_file}}` + +- Change the branch that `yadm` gets files from: + +`yadm clone {{remote_repository_location}} -b {{branch}}` + +- Override an existing repository local branch: + +`yadm clone {{remote_repository_location}} -f` diff --git a/pages/common/yadm-config.md b/pages/common/yadm-config.md new file mode 100755 index 000000000..63a438456 --- /dev/null +++ b/pages/common/yadm-config.md @@ -0,0 +1,20 @@ +# yadm-config + +> Pass options to `yadm`'s config file. Change the `.config` of the repository managed by `yadm`. +> See also: . + +- Set or update a `yadm`'s Git configuration: + +`yadm config {{key.inner-key}} {{value}}` + +- Get a value from `yadm`'s Git configuration: + +`yadm config --get {{key}}` + +- Unset a value in `yadm`'s Git configuration: + +`yadm config --unset {{key}}` + +- List all values in `yadm`'s Git configuration: + +`yadm config --list` diff --git a/pages/common/yadm-decrypt.md b/pages/common/yadm-decrypt.md new file mode 100755 index 000000000..bca698468 --- /dev/null +++ b/pages/common/yadm-decrypt.md @@ -0,0 +1,9 @@ +# yadm-decrypt + +> Decrypt files that were encrypted by `yadm`. +> When activating this command you will be prompted for a password. +> More information: . + +- Decrypt files: + +`yadm decrypt` diff --git a/pages/common/yadm-encrypt.md b/pages/common/yadm-encrypt.md new file mode 100755 index 000000000..2da5348b3 --- /dev/null +++ b/pages/common/yadm-encrypt.md @@ -0,0 +1,13 @@ +# yadm-encrypt + +> Encrypt files listed in the designated encrypt file. +> After the files are encrypted they will be save in the designated archive folder. +> More information: . + +- Encrypt files listed in the designated encrypt file: + +`yadm encrypt` + +- Create the necessary files and folders for encryption: + +`touch {{path/to/encrypt_file}} && mkdir {{path/to/archive_folder}}` diff --git a/pages/common/yadm-enter.md b/pages/common/yadm-enter.md new file mode 100755 index 000000000..7dfb5a7d2 --- /dev/null +++ b/pages/common/yadm-enter.md @@ -0,0 +1,13 @@ +# yadm-enter + +> Run a sub-shell with all Git variables set. This sub-shell can be used to easily interact with the local `yadm` repository using Git commands. +> This could be useful if you are using a tool which uses Git directly. +> More information: . + +- Run a sub-shell with all Git variables set: + +`yadm enter` + +- Exit the sub-shell: + +`exit` diff --git a/pages/common/yadm-git-crypt.md b/pages/common/yadm-git-crypt.md new file mode 100755 index 000000000..87611805f --- /dev/null +++ b/pages/common/yadm-git-crypt.md @@ -0,0 +1,21 @@ +# yadm git-crypt + +> Git Crypt enables transparent encryption and decryption of files in a git repository. +> See also: `git-crypt`. +> More information: . + +- Initialize repo to use Git Crypt: + +`yadm git-crypt init` + +- Share the repository using GPG: + +`yadm git-crypt add-gpg-user {{user_id}}` + +- After cloning a repository with encrypted files, unlock them: + +`yadm git-crypt unlock` + +- Export a symmetric secret key: + +`yadm git-crypt export-key {{path/to/key_file}}` diff --git a/pages/common/yadm-gitconfig.md b/pages/common/yadm-gitconfig.md new file mode 100755 index 000000000..088b5f005 --- /dev/null +++ b/pages/common/yadm-gitconfig.md @@ -0,0 +1,21 @@ +# yadm-gitconfig + +> Pass options to `git config`. Change the `.gitconfig` of the repository managed by `yadm`. +> See also: `git config`. +> More information: . + +- Update or set a Git configuration value: + +`yadm gitconfig {{key.inner-key}} {{value}}` + +- Get a value from `yadm`'s Git configuration: + +`yadm gitconfig --get {{key}}` + +- Unset a value in `yadm`'s Git configuration: + +`yadm gitconfig --unset {{key}}` + +- List all values in `yadm`'s Git configuration: + +`yadm gitconfig --list` diff --git a/pages/common/yadm-init.md b/pages/common/yadm-init.md new file mode 100755 index 000000000..d022783da --- /dev/null +++ b/pages/common/yadm-init.md @@ -0,0 +1,17 @@ +# yadm-init + +> Initialize a new, empty repository for tracking dotfiles. +> The repository is stored in `$HOME/.local/share/yadm/repo.git`. +> More information: . + +- Execute: + +`yadm init` + +- Override the worktree: + +`yadm init -w {{path/to/worktree_folder}}` + +- Overwrite an existing repository: + +`yadm init -f {{path/to/local_repository}}` diff --git a/pages/common/yadm-introsepct.md b/pages/common/yadm-introsepct.md new file mode 100755 index 000000000..307a9e507 --- /dev/null +++ b/pages/common/yadm-introsepct.md @@ -0,0 +1,21 @@ +# yadm-introspect + +> Look at data that is managed by `yadm`. +> The purpose of introspection is to support command line completion. +> More information: . + +- Output commands: + +`yadm introspect commands` + +- Output configs: + +`yadm introspect configs` + +- Output switches for the main `yadm` command: + +`yadm introspect switches` + +- Output repo: + +`yadm introspect repo` diff --git a/pages/common/yadm-list.md b/pages/common/yadm-list.md new file mode 100755 index 000000000..a5d8e11d9 --- /dev/null +++ b/pages/common/yadm-list.md @@ -0,0 +1,12 @@ +# yadm-list + +> Print a list of files managed by `yadm`. +> More information: . + +- Print a list of files managed by `yadm` in the current directory: + +`yadm list` + +- List all files managed by `yadm` completely: + +`yadm list -a` diff --git a/pages/common/yadm-perms.md b/pages/common/yadm-perms.md new file mode 100755 index 000000000..cd418b13d --- /dev/null +++ b/pages/common/yadm-perms.md @@ -0,0 +1,9 @@ +# yadm-perms + +> Update permissions. +> It is usually unnecessary to run this command, as `yadm` automatically processes permissions by default. This automatic behavior can be disabled by setting the configuration `yadm.auto-perms` to `"false"`. +> More information: . + +- Change file permissions: + +`yadm perms` diff --git a/pages/common/yadm-transcrypt.md b/pages/common/yadm-transcrypt.md new file mode 100755 index 000000000..bc4f1b665 --- /dev/null +++ b/pages/common/yadm-transcrypt.md @@ -0,0 +1,26 @@ +# yadm-transcrypt + +> If `transcrypt` is installed, this command allows you to pass options directly to `transcrypt`. +> With the environment configured to use the yadm repository. +> Transcrypt enables transparent encryption and decryption of files in a Git repository. +> More information: . + +- Set the symmetric cipher to utilize for encryption: + +`yadm transcrypt --cipher={{cipher}}` + +- Pass the password to derive the key from: + +`yadm transcrypt --password={{password}}` + +- Assume yes and accept defaults for non-specified options: + +`yadm transcrypt --yes` + +- Display the current repository's cipher and password: + +`yadm transcrypt --display` + +- Re -encrypt all encrypted files using new credentials: + +`yadm transcrypt --rekey` diff --git a/pages/common/yadm-upgrade.md b/pages/common/yadm-upgrade.md new file mode 100755 index 000000000..e6f0127c2 --- /dev/null +++ b/pages/common/yadm-upgrade.md @@ -0,0 +1,13 @@ +# yadm-upgrade + +> Upgrade `yadm` to the latest version. +> Upgrading will attempt to de-initialize and re-initialize your submodules. +> More information: . + +- Upgrade `yadm` to the latest version: + +`yadm upgrade` + +- Force the upgrade regardless of changes: + +`yadm upgrade -f` diff --git a/pages/common/yadm.md b/pages/common/yadm.md new file mode 100755 index 000000000..ac88733d7 --- /dev/null +++ b/pages/common/yadm.md @@ -0,0 +1,33 @@ +# yadm + +> A dotfiles manager that works by using `git`. +> Some subcommands such as `init`, `clone`, `push`, and `pull` have their own usage documentation. +> More information: . + +- Override the `yadm` directory. `yadm` stores its configurations relative to this directory: + +`yadm --yadm-dir` + +- Override the `yadm` data directory: `yadm` stores its data relative to this directory: + +`yadm --yadm-data` + +- Override the location of the `yadm` repository: + +`yadm --yadm-repo` + +- Override the location of the `yadm` configuration file: + +`yadm --yadm-config` + +- Override the location of the `yadm` encryption configuration: + +`yadm --yadm-encrypt` + +- Override the location of the `yadm` encrypted files archive: + +`yadm --yadm-archive` + +- Override the location of the `yadm` bootstrap program: + +`yadm --yadm-bootstrap`