This is a fork and isn't
intended to be directly used like the upstream. git clone
to a
$HOME
subdir is fine but dropping it directly into $HOME
is not
intended currently.
This README might be better as a gist, but it attempts to provide some rationale for the branches.
Note to future self: If it looks like it's just this file in here show dotfiles ;)
I feel that vcsh in conjunction with mr is a powerful combination yet also has the potential for simple user interaction. I'm not stupid and I'm pretty comfortable on the command line but I had some not-insignificant issues grokking how this all fits together to a level my perfectionist self was happy to proceed with. One source of my confusion was the template (there were many others, including relative inexperience with Git), so here's my attempt to unravel why and suggest some alternatives/improvements to aid understanding.
The original template is a directory structure with a couple of example config files to get one started with an integrated vcsh and mr setup. The original structure looks like this:
.
|-- .config/
| `-- mr/
| |-- available.d/
| | |-- mr.vcsh
| | `-- zsh.vcsh
| `-- config.d/
| `-- mr.vcsh -> ../available.d/mr.vcsh
`-- .mrconfig
I believe this presents some barriers to understanding which might be mitigated with some simple nomenclature alterations. It's internally consistent and makes sense as it is, but it assumes some prior knowledge on the user's part. I'll extend this structure slightly to incorporate some of the other recommendations in the vcsh documentation and in turn emphasise some of the issues I percieve.
.
|-- .config/
| `-- mr/
| |-- available.d/
| | |-- mr.vcsh
| | |-- zsh.vcsh
| | `-- mr.git
| `-- config.d/
| `-- mr.vcsh -> ../available.d/mr.vcsh
| `-- mr.git -> ..available.d/mr.git
`-- .mrconfig
I extended this to include mr.git
to emphasise a point of confusion
which will become apparent.
The contents of available.d/
(mr.vcsh
, zsh.vcsh
and mr.git
)
are mrconfig
snippets. The vcsh
suffix is just a convention to
imply that the config is referring to a vcsh-managed repo. Similarly,
the git
extension is merely convention to indicate it's pointing to
a "regular" Git repository (in this case, a local copy of mr).
The contents of config.d/
are symlinks to the snippets allowing one
to selectively expose them to mr
. The include
stanza in
.mrconfig
concatenates the snippets these symlinks point to. As an
aside, I highly approve of the XDG compliant .config/mr/
structure
and this modular approach is great.
So what's the problem?
The snippet nomenclature is ...confusing. vcsh
employs "fake-bare"
git repos (i.e. there's a repo pretending to be one without a work
tree, zsh.git
, in the vcsh data directory that the zsh.vcsh
snippet points at). There's no such thing as a vcsh
repo so as long
as you're aware of this, this by itself is perhaps not that confusing.
I specifically added the vcsh.git
snippet to illustrate how this can
become a source of confusion. I've included it in line with the
recommendations in the vcsh README to use the .git
extension to
indicate it's a "regular" Git repo (the README does also point out the
nomenclature is arbitrary, addressing this somewhat).
Why is this potentially confusing? Simply because it looks a lot like
a bare Git repo, fake or not. If you don't assume the user will infer
this from knowing *.vcsh
can't be repos, it might not be apparent
these are config files at all until they look closer. Obviously you
don't have to look much closer to figure this out, but on scanning the
README?
However, this is mitigated by...
The *.d
nomenclature implies that the contents are config
snippets. Fair enough, but this relies on the user being familiar with
this convention. Aside from convention, is there any real reason why
the suffix is required? It's not like it makes sense for there to be a
.../mr/config
or .../mr/available
.
One slightly larger issue I have with the default nomenclature is the
use of .../mr/config.d/
. I get that the contents imply a mr-managed
configuration so it makes sense on that level, but it's all config on
some level in the end...
Ultimately, the nomenclature here is arbitrary. The nature of the beast allows users to bypass this template entirely and configure as they see fit. The point of the template, however, is to get users started and, I would argue, provide some assistance in understanding the back-end concepts (which is actually currently a pre-requisite to using vcsh confidently, IMO).
I've created a number of branches illustrating iterative changes to the original template which aim to improve conceptual clarity, each building on the previous.