]> git.madduck.net Git - code/vcsh.git/blobdiff - doc/vcsh.1.ronn

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Improve hook documentation
[code/vcsh.git] / doc / vcsh.1.ronn
index 0ea94286e26fc64ca2e8b4637dbd9b3976031b41..6a04b13dabcacd205e303eb7dcb92c9bf5be8958 100644 (file)
@@ -1,5 +1,5 @@
-vcsh(1) - manage and sync config files via git
-==============================================
+vcsh(1) - manage config files in $HOME via fake bare git repositories
+=====================================================================
 
 ## SYNOPSIS
 
@@ -15,16 +15,22 @@ vcsh(1) - manage and sync config files via git
 
 `vcsh` list
 
+`vcsh` list-tracked
+
+`vcsh` list-tracked-by <repo>
+
 `vcsh` rename <repo> <newname>
 
 `vcsh` run <repo> <command>
 
-`vcsh` seed-gitignore <repo>
-
 `vcsh` setup <repo>
 
+`vcsh` write-gitignore <repo>
+
 `vcsh` <repo> <gitcommand>
 
+`vcsh` <repo>
+
 
 ## DESCRIPTION
 
@@ -68,6 +74,12 @@ an interactive user.
 * 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.
 
@@ -82,24 +94,61 @@ an interactive user.
   This is needed to support mr and other scripts properly and of no concern to
   an interactive user.
 
-* seed-gitignore:
-  Seed .gitignore.d/<repo> from git ls-files.
-
 * setup:
   Set up repository with recommended settings.
 
+* write-gitignore:
+  Write .gitignore.d/<repo> via git ls-files.
+
 * <repo> <gitcommand>:
   Shortcut to run `vcsh` on a repo. Will prepend `git` to <command> by itself.
 
+* <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,
-speaking, adding a `sudo`(8) rule for `vcsh` would be pretty stupid.
+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