VCSH(1) 																   VCSH(1)

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 reposi-
	      tory'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)

								     June 2012								   VCSH(1)