{"id":17494340,"url":"https://github.com/lkubb/salt-tool-template-formula","last_synced_at":"2025-08-05T05:30:47.684Z","repository":{"id":134852560,"uuid":"483850274","full_name":"lkubb/salt-tool-template-formula","owner":"lkubb","description":"A heavily modified variant of the official template formula for Cookiecutter. Serves as a base for several formulae that configure the user / developer environment with Salt.","archived":false,"fork":false,"pushed_at":"2024-11-05T06:50:13.000Z","size":1386,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-11-05T07:31:12.489Z","etag":null,"topics":["cookiecutter-template","development-environment","devops","dotfiles","salt-formula","saltstack"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lkubb.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-04-21T00:04:51.000Z","updated_at":"2024-11-05T06:50:17.000Z","dependencies_parsed_at":"2023-12-07T03:01:33.314Z","dependency_job_id":null,"html_url":"https://github.com/lkubb/salt-tool-template-formula","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lkubb%2Fsalt-tool-template-formula","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lkubb%2Fsalt-tool-template-formula/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lkubb%2Fsalt-tool-template-formula/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lkubb%2Fsalt-tool-template-formula/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lkubb","download_url":"https://codeload.github.com/lkubb/salt-tool-template-formula/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228705254,"owners_count":17959952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cookiecutter-template","development-environment","devops","dotfiles","salt-formula","saltstack"],"created_at":"2024-10-19T13:06:14.749Z","updated_at":"2024-12-08T08:20:20.837Z","avatar_url":"https://github.com/lkubb.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Cookiecutter Template for ``salt-tool`` Formulae\n================================================\n\nThis ``cookiecutter`` template is a heavily modified variant of the `official template-formula \u003chttps://github.com/saltstack-formulas/template-formula\u003e`_ that aims to ease the process of writing userland formulae in the style of the ``tool`` suite.\n\nAbout ``tool`` Suite\n--------------------\nThis term describes a bunch of formulae that I wrote to setup and manage my personal systems (examples: ``zsh``, ``git``, ``gnupg``, ``ssh``, ``vim``, ``asdf``, ``Firefox``, ``Yabai``). I will create a better overview of those once I get ready to publish them.\n\nThe underlying problem was that Salt is generally used to setup server environments, which operates on the system scope. To manage the user environment, I had to bend the available tools a bit.\n\nPrerequisites\n-------------\nCookiecutter\n~~~~~~~~~~~~\n* This cookiecutter currently needs to be `modified \u003chttps://github.com/lkubb/cookiecutter/tree/fix-with-alt-jinjatags\u003e`_ to find the template files with the alternative syntax, otherwise it will complain about this not being a template. (@TODO pull request)\n* Also, since PR #1692, cookiecutter does not support dicts with new keys, which breaks my use case. Hence I `removed this breaking change again \u003chttps://github.com/lkubb/cookiecutter/tree/my\u003e`_.\n\nCruft\n~~~~~\n`Cruft \u003chttps://github.com/cruft/cruft\u003e`_ is a wrapper around ``cookiecutter`` that takes care of maintaining the boilerplate. It allows you to show the diff between what the template generated and the current state with ``cruft diff`` and to apply updates from the template with ``cruft update`` (and more).\n\nCruft currently also needs to be very recent and modified to `support cookiecutter v2 \u003chttps://github.com/lkubb/cruft/tree/fix-template-extensions\u003e`_ and the `alternative Jinja syntax \u003chttps://github.com/lkubb/cruft/tree/v2-jinjaenv\u003e`_. Both changes are found in the `my branch \u003chttps://github.com/lkubb/cruft/tree/my\u003e`_ of my fork. (@TODO pull request)\n\nExample Installation\n~~~~~~~~~~~~~~~~~~~~\nSince I use ``pipx`` to manage python programs in their own isolated environments, my installation goes as follows:\n\n.. code-block:: bash\n\n    pipx install git+https://github.com/lkubb/cruft.git@my\n    pipx runpip cruft uninstall cookiecutter\n    pipx runpip cruft install git+https://github.com/lkubb/cookiecutter.git@my\n\nPip might complain about some dependencies, but it works.\n\nUsage\n-----\nFirst Creation\n~~~~~~~~~~~~~~\nCreating a new formula from this template is as easy as:\n\n.. code-block:: bash\n\n    cookiecutter https://github.com/lkubb/salt-tool-template-formula\n\nFor cookiecutter, this is where the journey ends.\n\nThe recommended way to use this template goes a little further though, since (a) there are hidden variables with further configuration and (b) updates from the template are cumbersome. This is where cruft steps in.\n\n.. code-block:: bash\n\n    cruft create https://github.com/lkubb/salt-tool-template-formula\n\nCustomization\n~~~~~~~~~~~~~\nHaving created the formula with cruft, you will find a ``.cruft.json`` file in the root directory. This saves your answers and allows you to edit some hidden variables. Those are currently for parameters to the formula, sorted into:\n\n- ``lookup``: Custom lookup variables for data that the user should not have to modify regularly.\n- ``settings``: Global settings for this formula.\n- ``usersettings``: Settings that are available per-user.\n\nOnce you have modified those, run ``cruft diff | git apply`` to recreate the formula. **Warning**: This command resets the state to the autogenerated one, so take care if you have modified any files manually at this point. In that case, you can pipe the output into a file and manually select the changes: ``cruft diff \u003e temp.patch``, edit and then ``git apply temp.patch``.\n\nParameters\n----------\nThis is an overview of the available parameters for autogeneration. The most recent version is found in ``cookiecutter.json`` though and might be out of sync.\n\nname [str]\n    The name of the managed program. Example: ``Google Chrome``.\n\nabbr [str]\n    A slugified version of ``name``. Example: ``google-chrome``.\n\nabbr_pysafe [str]\n    A short and pythonic version of ``abbr``. Example: ``google_chrome`` or ``chrome``. This will be used in many places, including the formula base dir (``tool_chrome``), the pillar key and the Jinja variable name.\n\npkg [str]\n    The default package name of the program. Example: ``google-chrome``, ``gnupg``.\n\nmodstate [bool]\n    Whether this formula will provide custom execution/state modules. This will autogenerate a skeleton for both and include hints in the docs.\n\nneeds_repo [bool]\n    Whether the package installation relies on custom repositories (for Linux). This will add boilerplate for those in the ``parameters/os_family`` files as well as sls files to install them.\n\nhas_service [bool]\n    Whether a service is to be managed.\n\nmac_library [bool]\n    Whether on MacOS, the default configuration lives in ``~/Library/Application Support``.\n\nmac_cask [bool]\n    Whether on MacOS, the package is a cask.\n\nhas_xdg [bool]\n    Whether the formula should have some kind of XDG spec support.\n\nneeds_xdg_help [bool]\n    If has_xdg and the program does not act that way by default, whether you will provide a way to migrate the data and enforce complicance.\n\nhas_conffile_only [bool]\n    If the program only has a configuration file (e.g. ``.gitconfig``).\n\ndefault_confdir [str]\n    The default configuration directory on Linux. Can be empty for ``$HOME``.\n\ndefault_confdir_mac [str]\n    The default configuration directory on MacOS. Can be empty for ``$HOME``.\n\ndefault_conffile [str]\n    The name of the default configuration file. Example: ``.gitconfig``.\n\nxdg_dirname [str]\n    The name of the directory in XDG dirs for this program (e.g. ``git``).\n\nxdg_conffile [str]\n    The name of the configuration file inside ``~/.config/\u003cxdg_dirname\u003e``. Example: ``config``.\n\nhas_configsync [bool]\n    Whether the formula provides automatic syncing of configuration files from a dotfiles repository.\n\nhas_config_template [bool]\n    Whether the formula provides a way to serialize parameters into the program's config file.\n\nhas_completions [bool]\n    Whether the formula provides a way to install shell completions for the program.\n\nhas_tests [bool]\n    Whether the formula should have test boilerplate code. This is only provided for Linux at the moment, so MacOS-only formulae should answer ``n`` here.\n\ngit_username [str]\n    Your Github/Gitlab/... username that should be used as the author of the formula.\n\nlookup [map/dict]\n    An arbitrarily nested mapping/dictionary that describes lookup data that the user should not have to modify. Examples include package dependencies, some paths, package names etc.\n\nsettings [map/dict]\n    An arbitrarily nested mapping/dictionary that describes global parameters for the formula. Examples include package version and system configuration for the managed program.\n\nusersettings [map/dict]\n    An arbitrarily nested mapping/dictionary that describes per-user parameters for the formula. Examples include list of plugins to install, user configuration for the managed program.\n\n\nReferences\n----------\n* https://github.com/saltstack-formulas/template-formula\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flkubb%2Fsalt-tool-template-formula","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flkubb%2Fsalt-tool-template-formula","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flkubb%2Fsalt-tool-template-formula/lists"}