NAME¶

vcsh - manage config files in $HOME via fake bare git repositories

SYNOPSIS¶

vcsh clone url [repo] vcsh delete repo vcsh enter repo vcsh help vcsh init repo vcsh list vcsh list-tracked vcsh list-tracked-by repo vcsh rename repo newname vcsh run repo command vcsh setup repo vcsh which substring vcsh write-gitignore repo vcsh repo gitcommand vcsh repo

DESCRIPTION¶

vcsh allows you to have several git(1) repositories, all maintaining their working trees in $HOME without clobbering each other. That, in turn, means you can have one repository per config set (zsh, vim, ssh, etc), picking and choosing which configs you want to use on which machine. vcsh is using a technique called fake bare git repositories, keeping $GIT_DIR in a different directory from $GIT_WORK_TREE which is pointed to $HOME. The use of symlinks is not needed in this setup, making for a cleaner setup. vcsh was designed with mr(1) in mind so you might want to install it alongside vcsh. That being said, you can easily use vcsh without mr if you prefer. A sample configuration for vcsh and mr can be found at https://github.com/RichiH/vcsh_mr_template and used with vcsh clone https://github.com/RichiH/vcsh_mr_template mr. Please note that you can always use a path instead of a name for repo. This is needed to support mr and other scripts properly and of no concern to an interactive user.

OPTIONS¶

clone

Clone an existing repository.

delete

Delete an existing repository.

enter

Enter repository; spawn new $SHELL.

help

Display help.

init

Initialize an empty repository.

list

List all local vcsh repositories.

list-tracked

List all files tracked by vcsh.

list-tracked-by

List files tracked by a repository.

rename

Rename a repository.

run

Run command with $GIT_DIR and $GIT_WORK_TREE set. Allows you to run any and all commands without any restrictions. Use with care.

Please note that there is a somewhat magic feature for run. Instead of repo it accepts path, as well. Anything that has a slash in it will be assumed to be a path. vcsh run will then operate on this directory instead of the one normally generated from the repository´s name. This is needed to support mr and other scripts properly and of no concern to an interactive user.

setup

Set up repository with recommended settings.

which substring

Find substring in name of any tracked file.

write-gitignore

Write .gitignore.d/repo via git ls-files.

repo gitcommand

Shortcut to run vcsh on a repo. Will prepend git to command.

repo

Shortcut to run vcsh enter <repo>.

ENVIRONMENT¶

As noted earlier, vcsh will set $GIT_DIR and $GIT_WORK_TREE to the appropriate values for fake bare git repositories.

HOOK SYSTEM¶

vcsh provides a hook system. Hook scripts must be executable and should be placed in <$XDG_CONFIG_HOME/vcsh/hooks-available>. From there, they can be soft-linked into <$XDG_CONFIG_HOME/vcsh/hooks-enabled>; vcsh will only execute hooks that are in this directory. Hooks follow a simple format. pre-run will be run before anything is run. If you want to have more than one script for a certain hook, just append any kind of string to order them. A system of pre-run, <pre-run.10>, <pre-run.20> etc is suggested; other options would be pre-run-10 or <pre-run.sh>. A dot after the hook name is optional. If you want to create hooks for a specific vcsh repository, simply prepend the repository´s name, followed by a dot, i.e. <zsh.pre-run>. Otherwise, the same rules as above apply. The dot between the repository´s name and the hook is mandatory, though. Available hooks are pre-enter, post-enter, pre-run, post-run, pre-setup, and post-setup. If you need more, vcsh is trivial to patch, but please let upstream know so we can ship them by default.

DETAILED HOWTO AND FURTHER READING¶

Man pages are intended to be short and thus often useless to glean best practices from. This software comes with a file called <README.md>. It contains various approaches to setting up and using vcsh. You can view the file it as plain text or render it into various other formats via Markdown. On Debian-based systems, this file can be found in </usr/share/doc/vcsh>.

SECURITY CONSIDERATIONS¶

vcsh allows you to execute arbitrary commands via vcsh run. For example, adding a sudo(8) rule for vcsh would be pretty stupid. Additionally, vcsh will source, i.e. execute, <$XDG_CONFIG_HOME/vcsh/config>. You can put any and all commands into this config file and they will be executed.

BUGS¶

None are known at this time, but reports and/or patches are more than welcome.

KNOWN ISSUES¶

As of this writing (June 2012), vcsh does not work with git submodule due to limitations within git. Depending on when you are reading this, you might want to consider upgrading.

HISTORY¶

Like most people, the author initially made do with a single repository for all config files, all of which were soft-linked into $HOME. Martin F. Krafft aka madduck came up with the concept of fake bare git repositories. vcsh was initally written by madduck. This version is a re-implementation from scratch with a lot more features. madduck graciously agreed to let the author take over the name.

AUTHOR¶

This manpage and vcsh itself were written by Richard "RichiH" Hartmann.

COPYRIGHT¶

Copyright 2011-2012 Richard Hartmann richih.mailinglist@gmail.com Licensed under the GNU GPL version 2 or higher. https://github.com/RichiH/vcsh

SEE ALSO¶

git(1), mr(1)