From 97a112770d6d05387d57a57b3b4c8a10bb9a17a0 Mon Sep 17 00:00:00 2001 From: Erich Gubler Date: Tue, 25 Oct 2022 08:46:57 -0600 Subject: [PATCH] docs: add WIP examples of different TOML files for config portability --- concepts.md | 26 +++++++++++++++ repo_example.toml | 21 ++++++++++++ starter_example.toml | 51 +++++++++++++++++++++++++++++ template_example.kdl | 74 +++++++++++++++++++++++++++++++++++++++++++ template_example.toml | 59 ++++++++++++++++++++++++++++++++++ 5 files changed, 231 insertions(+) create mode 100644 concepts.md create mode 100644 repo_example.toml create mode 100644 starter_example.toml create mode 100644 template_example.kdl create mode 100644 template_example.toml diff --git a/concepts.md b/concepts.md new file mode 100644 index 0000000..1e13188 --- /dev/null +++ b/concepts.md @@ -0,0 +1,26 @@ +```mermaid +flowchart TD + seeds[Seeds: well-known app configuration repo locations]; + starter[Starters: editable exports of existing remote repos]; + + local_repos[Local Git repos] + remote_repos[Remote Git repos]; + + local_repos --> remote_repos; + remote_repos --> local_repos; + + command_new_from_file([`cpsc new from-seed`]); + command_import([`cpsc starter import`]); + command_export([`cpsc starter export`]); + + command_new_from_file -->|creates single| local_repos; + command_import -->|creates multiple| local_repos; + + seeds --> command_new_from_file; + local_repos --> command_export; + + command_export -->|export to| starter; + starter -->|set up clones for| command_import; + + apps[3rd party applications with their own config locations] -->|seed-ified by Capisco community| seeds; +``` diff --git a/repo_example.toml b/repo_example.toml new file mode 100644 index 0000000..68b53c4 --- /dev/null +++ b/repo_example.toml @@ -0,0 +1,21 @@ +# This is a local repository configuration for [Capisco], likely created via +# `cpsc new`. If you find the need to edit this manually, it's almost certainly +# a bug or out-of-date template definition. Please file an issue +# [upstream][issue tracker]! +# +# [Capisco]: https://github.com/capisco-dotfiles/capisco +# [issue tracker]: https://github.com/capisco-dotfiles/capisco + +[capisco] +type = "repo" +schema_version = "1" + +[repo] +checkout_location = { type = "xdg", subdir = "nvim" } + +[history.template] +source = "https://github.com/capisco-dotfiles/templates" +rev = "ASDFASDFASDF" +template = "neovim" +variant = "default" +version = 1 diff --git a/starter_example.toml b/starter_example.toml new file mode 100644 index 0000000..0caa46f --- /dev/null +++ b/starter_example.toml @@ -0,0 +1,51 @@ +# This file is a _Capisco starter file_. It's used with [Capisco] (a dotfiles +# management tool) to clone multiple dotfiles repositories with a single +# command, i.e.: +# +# ```sh +# $ cpsc export $THIS_FILE # save current configuration of repos +# $ cpsc import $THIS_FILE # load configuration back again +# ``` +# +# [Capisco]: https://github.com/capisco-dotfiles/capisco + +[capisco] +type = "starter" +schema_version = "1" + +[throwaway] +git_url = "https://github.com/throwaway-fanboy/throwaway" +# # The following are optional values with their default values provided for +# # illustration: +# remote_name = "origin" +# branch = "main" # Falls back to `"master"`, if not found. + +# # Additional remotes can be added using sub-tables of `.remotes`. For +# # example, if we wanted to add an `upstream` remote, we could do so like +# # this: +# [throwaway.remotes.upstream] +# git_url = "https://github.com/throwaway/throwaway" + +# # TODO: Template selection, or actual assignment? I think we should go with +# # assignment for now, but I'm not sure. +# # +# # For best experience with your own repos, it's strongly recommended you +# # embed a repository configuration (`capisco.toml`) in them. However, you can +# # also specify or override a configuration here. It uses the same schema as +# # [template file entries]. +# # +# # [template file entries]: TODO +# [throwaway.template] +# name = "neovim" +# +# [throwaway.template.override.windows] +# standalone = "" + +[git] +git_url = "git@github.com:erichdongubler-dotfiles/git" + +[neovim] +git_url = "git@github.com:erichdongubler-dotfiles/neovim" + +[nushell] +git_url = "git@github.com:erichdongubler-dotfiles/nushell" diff --git a/template_example.kdl b/template_example.kdl new file mode 100644 index 0000000..f3b45be --- /dev/null +++ b/template_example.kdl @@ -0,0 +1,74 @@ +// This is a template definition file for [Capisco]. If you find the need to +// edit one of these manually, it's almost certainly a bug, missing, or +// out-of-date. Please file an issue [upstream][issue tracker]! +// +// [Capisco]: https://github.com/capisco-dotfiles/capisco +// [issue tracker]: https://github.com/capisco-dotfiles/capisco + +capisco-header { + type "template" + schema-version 1 +} + +template git { + version 1 default-variant=home-dir-gitconfig { + home-dir-gitconfig { + all { + type "overlay" + root "~" + files { + .gitconfig + } + } + } + xdg { + type "global" + // `subdir` is inferred to be the template's name when omitted + } + } +} + +template neovim { + version 1 { + default { + unix { + checkout-location { + type "xdg" + subdir "nvim" + } + } + windows { + checkout-location { + type "windows-local-appdata" + app-name "nvim" + } + } + } + } +} + +template nushell { + version 1 { + all { + checkout_location { + type "native" + qualifier "" + org "" + app "nushell" + } + } + } +} + +template espanso { + version 1 { + all { + checkout_location { + type "native" + qualifier "" + org "" + app "nushell" + } + } + } +} diff --git a/template_example.toml b/template_example.toml new file mode 100644 index 0000000..87597aa --- /dev/null +++ b/template_example.toml @@ -0,0 +1,59 @@ +# This is a template definition file for [Capisco]. If you find the need to +# edit one of these manually, it's almost certainly a bug, missing, or +# out-of-date. Please file an issue [upstream][issue tracker]! +# +# [Capisco]: https://github.com/capisco-dotfiles/capisco +# [issue tracker]: https://github.com/capisco-dotfiles/capisco + +[capisco] +type = "template" +schema_version = "1" + +# --- + +[template] +name = "git" + +[[versions]] +number = 1 +# TODO: Maybe use a `default_variant = false` to force a user to pick? +default_variant = "home_dir_gitconfig" # defaults to `"default"` + +[template.variants.home_dir_gitconfig] +checkout_location = { type = "overlay", files = [".gitconfig"] } + +[template.variants.xdg] +checkout_location = { type = "xdg" } # `subdir` is omitted, and inferred to be `template.name`'s value + +# --- + +[template] +name = "neovim" +# version = 1 +# default_variant = "default" + +[template.variants.default] +checkout_location = { type = "xdg", subdir = "nvim" } +# # If we actually wanted the `neovim` segment, we could go with: +# standalone = { type = "xdg" } + +[template.variants.default.windows] +checkout_location = "~/AppData/Local/nvim" # Paths _must_ start with `~`. If you'd like to see this relaxed, holler at . + +# --- + +[template] +name = "nushell" + +[template.variants.default] +checkout_location = { type = "native" } +# # The above is shorthand for: +# checkout_location = { type = "native", qualifier = "", org = "", app = "nushell" } + +# --- + +[template] +name = "espanso" + +[template.variants.default] +checkout_location = { type = "native" }