Package: dotmgr
What isdotmgr?dotmgris a little helper script you can use to manage and deploy your dotfiles or other configs
across multiple machines.The idea is to define tags for individual hosts and/or types of devices such as "laptop",
"headless", "work", "server" and use those to filter ("specialize") dotfiles by commenting out
blocks. Therefor the dotfiles have to be decorated with markup comments controlling the filter.Dotfile "templates" are stored in a git repository so you can track and possibly revert your changes
or get totally schwifty by combining the powers ofdotmgrand git branches.Specialized dotfiles are written directly to your home directory. Changes made to those files can
later be merged back into the repository by applying an inverted ("generalize") filter.FeaturesStore and maintain dotfiles containing different sets of configurations in a git repository.Maintain specific versions of dotfiles in your home directory (or anywhere on the file system)
and merge changes back.Filter files based on defined tags (or simply hostnames) and/or user name.Ignore files based on the same rules so they don't pollute your home directory.Concise command-line interface inspired by pacman.How it worksDotfile repositoryDotfile templates - also called "generic dotfiles" - are stored in a git repository. Each dotfile's
path relative to the repository's root directory is the same as relative to your home directory.Special comments in the dotfiles are used to indicate blocks ("tagged blocks") that should either be
commented out or left intact, depending on the tags activated for a host. Lines not enclosed by a
tagged block directives are always left untouched. Note that for this to work, the first line of a
dotfilemustbegin with a comment sodotmgrcan identify the comment character sequence
(#for bash,--for lua,"for vim, ...).The dotfile repository path default is~/.local/share/dotmgr/repository. It can be modified using
the environment variable$DOTMGR_REPO.Tag configurationThe script relies on a simple configuration file that defines active tags for hostnames in the
following format:hostnameA: tagA1 tagA2 ...
hostnameB: tagB1 tagB2 ...This file is normally read from.config/dotmgr/tags.confin your home directory or, if that file
does not exist, directly from dotfile repository.If for some reason this does not suit you, setting the environment variable$DOTMGR_TAG_CONFlets
you override the default path. It is however not recommended.Command-line interfacedotmgr's clean command-line interface lets you add dotfiles from your home directory to the
repository, filter (specialize/generalize) them according to your tag configuration and filter
directives or remove them from the repository in case they become obsolete. It also lets you
perform common git tasks with the flick of a switch.UsageInstallationYou can install the script viapip, which will conveniently take care of dependencies:pip install dotmgrIt is important that you use the Python 3 version ofpip. If in doubt, callpip3explicitly:pip3 install dotmgrInitial runIf you already have a repository containing your dotfiles, you can simply clone it:dotmgr -I git@github.com:<user>/dotfiles.gitIf the tag configuration is not found,dotmgrwill automatically create one and commit it.
If you do not have a repository yet, you can letdotmgrcreate one for you:dotmgr -IThis will also generate and commit an initial tag configuration.When the repository is set up, you can specialize all dotfiles:dotmgr -SData- and workflowThe following diagram summarizes the data-/workflow and associated command-line parameters:You can telldotmgrabout a new dotfile it should care about by issuing:dotmgr -G <file>It will automatically generalize the file and copy the result to your repository.After you have changed a file, you can re-generalize it, for example:dotmgr -G .vimrcOmitting the file path (which has to be a path relative to your home directory) lets you generalize
all dotfiles at once.When files in the dotfile repository change, you can apply those changes to your dotfiles:dotmgr -SIf you want to specialize only a single file, just add its path to the command line.To forget about a file, delete it from the repository:dotmgr -D <file>Please refer to the scripts--helpoption for more information on command line options and
arguments.Git integrationThe program can interact with the repository and automate or at least simplify some pretty
repetitive actions when managing dotfiles:-Iinitializes or clones remote repositories as shown inInitial run.-cautomatically commits changes to dotfiles (using generated or custom commit messages).-sautomatically synchronizes with a remote repository before specialization / after generalization.-Vlets you execute git commands in the dotfile repository without having tocdinto it first.Please refer to--helpfor details on the command-line syntax.ConfigurationDotfile specialization / generalizationThis is the workflow for generating specific dotfiles for the current hostname and installing them
in the system:Read hostname and the tags activated for it this host from the tag configurationRead dotfiles from the repositorySpecialize / generalize dotfiles by uncommenting / commenting blocks with matching tagsWrite them to the home directoryWhen changed dotfiles are generalized and merged back to the dotfile repository, all changes of the
specialization are reversed by removing all comments from tagged blocks.Tagged blocksCreate tagged blocks using a double comment sequence and the directiveonlyornot. A double
comment sequence followed byendends a tagged block. The following example assumes that the
comment character for the file is#- of course the same is possible for other file types as well:##only desktop laptop
# ordinary comment
firefox
##end

##not headless
numlockx
##endYou can leave out the##enddirective on sequential lines / blocks:##only tagA
echo Hello dotmgr
fortune
##not tagB
echo Cheers dotmgr
##endIf you have multiple accounts on a host (maybe root and a user account) and you want to customize
your dotfiles based on these, you can use an e-mail / SSH-style syntax in all directives:##only operator@reactor
warnings=ignore
##not guest@reactor
allow_shutdown=yes
##endIf you want a particular user to have the same set of files and configuration on all devices, you
can use the syntax<user>@*in tag definitions. This is probably most useful with admin accounts
such asroot. Please seeSkipping filesbelow for an example.SpecialdotmgrheaderDuring specialization, files can be written to arbitrary locations or skipped completely on hosts
with certain tags by adding a specialdotmgrheader to it.# dotmgr
##use not server
##end

[...]As with tag-blocks, theenddirective marks the end of the header block. Everything after it is
treated as "normal" file content.Skipping filesTheusedirective allows you to skip ignore files during specialization.Syntax:use (only|not) <tag> [<tag> ...]Example:% dotmgr
%%use not root@*
%%

yada yada
[...]Parametersonlyandnothave the same effect as in tagged-blocks.Custom pathsYou can store files anywhere on you machine by specifying a custom path using thepathdirective:Syntax:path <path> <tag> [<tag> ...]Example:# dotmgr
##path /etc/hosts root@server
##endIf thepathdirective is present in the header and the host's active tags do not match, the file
is automatically skipped.Advanced vim magicAdding the following line to your .vimrc automagically invokes the script each time you save a
dotfile in your home directory:autocmd BufWritePost ~/.* !dotmgr -G %DevelopmentSetuppython-mvenvvenv
.venv/bin/activate
pipinstall-e'.[dev]'# All of the following should succeedmypysrc
pylintsrc
pytestDeploymentpython-mbuild
twineuploaddist/*Documentationsphinx-builddocs/sphinxdocs/generated