]> 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:

projects / code / vcsh.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Update licensing info
[code/vcsh.git] / doc / vcsh.1.ronn
diff --git a/doc/vcsh.1.ronn b/doc/vcsh.1.ronn
index 11db1efa6358061d7537c3833b7983ecc2fd2d52..f286dc0b4f57ccb6815b5c91718daadd0815d7df 100644 (file)
--- a/doc/vcsh.1.ronn
+++ b/doc/vcsh.1.ronn
@@ -3,6 +3,8 @@ vcsh(1) - manage config files in $HOME via fake bare git repositories
 
 ## SYNOPSIS
 
 
 ## SYNOPSIS
 
+`vcsh` [<options>] <command>
+
 `vcsh` clone <url> [<repo>]
 
 `vcsh` delete <repo>
 `vcsh` clone <url> [<repo>]
 
 `vcsh` delete <repo>
@@ -21,7 +23,7 @@ vcsh(1) - manage config files in $HOME via fake bare git repositories
 
 `vcsh` rename <repo> <newname>
 
 
 `vcsh` rename <repo> <newname>
 
-`vcsh` run <repo> <command>
+`vcsh` run <repo> <shell command>
 
 `vcsh` setup <repo>
 
 
 `vcsh` setup <repo>
 
@@ -29,7 +31,7 @@ vcsh(1) - manage config files in $HOME via fake bare git repositories
 
 `vcsh` write-gitignore <repo>
 
 
 `vcsh` write-gitignore <repo>
 
-`vcsh` <repo> <gitcommand>
+`vcsh` <repo> <git command>
 
 `vcsh` <repo>
 
 
 `vcsh` <repo>
 
@@ -59,6 +61,17 @@ an interactive user.
 
 ## OPTIONS
 
 
 ## OPTIONS
 
+* -c:
+  Source <file> prior to other configuration files
+
+* -d:
+  Enable debug mode
+
+* -v:
+  Enable verbose mode
+
+## COMMANDS
+
 * clone:
   Clone an existing repository.
 
 * clone:
   Clone an existing repository.
 
@@ -101,13 +114,13 @@ an interactive user.
   Set up repository with recommended settings.
 
 * which <substring>:
   Set up repository with recommended settings.
 
 * which <substring>:
-  Find <substring> in any tracked file name.
+  Find <substring> in name of any tracked file.
 
 * write-gitignore:
   Write .gitignore.d/<repo> via git ls-files.
 
 * <repo> <gitcommand>:
 
 * 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.
+  Shortcut to run `vcsh` on a repo. Will prepend `git` to <command>.
 
 * <repo>:
   Shortcut to run `vcsh enter <repo>`.
 
 * <repo>:
   Shortcut to run `vcsh enter <repo>`.
@@ -117,6 +130,59 @@ an interactive user.
 As noted earlier, `vcsh` will set <$GIT_DIR> and <$GIT_WORK_TREE> to the
 appropriate values for fake bare git repositories.
 
 As noted earlier, `vcsh` will set <$GIT_DIR> and <$GIT_WORK_TREE> to the
 appropriate values for fake bare git repositories.
 
+## CONFIG
+
+There are several ways to turn the various knobs on `vcsh`. In order of
+ascending precedence, they are:
+
+* `VARIABLE=foo vcsh`
+* </etc/vcsh/config>
+* <$XDG_CONFIG_HOME/vcsh/config>
+* `vcsh -c <file>`
+
+Please note that those files are sourced. Any and all commands will be
+executed in the context of your shell.
+
+Interesting knobs you can turn:
+
+* <$VCSH_GITIGNORE>:
+  Can be either <exact> or <recursive>.
+
+  <exact> will seed the repo-specific <.gitignore> with all file and directory
+  names which `git ls-files` returns.
+
+  <recursive> will descend through all directories recursively additionally to
+  the above.
+
+  Defaults to <exact>.
+
+Less interesting knobs you could turn:
+
+* <$VCSH_DEBUG>:
+  Enter debug mode.
+
+* <$XDG_CONFIG_HOME>:
+  As specified in the 'XDG Base Directory Specification', see
+  <http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>
+
+  Defaults to <$HOME/.config>.
+
+* <$VCSH_REPO_D>:
+  The directory where repositories are read from and stored.
+
+  Defaults to <$XDG_CONFIG_HOME/vcsh/repo.d>.
+
+* <$VCSH_HOOK_D>:
+  The directory where hooks are read from.
+
+  Defaults to <$XDG_CONFIG_HOME/vcsh/hooks-enabled>.
+
+* <$VCSH_BASE>:
+  The directory where repositories are checked out to.
+
+  Defaults to <$HOME>.
+
+
 ## HOOK SYSTEM
 
 `vcsh` provides a hook system. Hook scripts must be executable and should be
 ## HOOK SYSTEM
 
 `vcsh` provides a hook system. Hook scripts must be executable and should be
@@ -141,25 +207,34 @@ but please let upstream know so we can ship them by default.
 
 ## DETAILED HOWTO AND FURTHER READING
 
 
 ## 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
+Manpages are often short and sometimes useless to glean best practices from.
+While the author tried to avoid this in this case, manpages can not cover
+detailed howtos.
+
+This software also 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
 
 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,
+`vcsh` allows you to execute arbitrary commands via `vcsh run`. For example,
 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.
+Additionally, vcsh will source, i.e. execute, all files listed in <CONFIG>.
+You can put any and all commands into these config files and they will be
+executed.
 
 ## BUGS
 
 None are known at this time, but reports and/or patches are more than welcome.
 
 
 ## BUGS
 
 None are known at this time, but reports and/or patches are more than welcome.
 
+## INTEROPERABILITY
+
+If you rely on `git submodule`, use `git` 1.7.12 or later. Earlier versions
+do not clean internal variables properly before descending into a submodule.
+
 ## HISTORY
 
 Like most people, the author initially made do with a single repository for all
 ## HISTORY
 
 Like most people, the author initially made do with a single repository for all
@@ -180,7 +255,7 @@ This manpage and `vcsh` itself were written by Richard "RichiH" Hartmann.
 
 Copyright 2011-2012 Richard Hartmann <richih.mailinglist@gmail.com>
 
 
 Copyright 2011-2012 Richard Hartmann <richih.mailinglist@gmail.com>
 
-Licensed under the GNU GPL version 3 or higher.
+Licensed under the GNU GPL version 2 or higher.
 
 https://github.com/RichiH/vcsh
 
 
 https://github.com/RichiH/vcsh
 
version controlled RC files

Legalese

All content available in this repository is copyright © martin f. krafft, unless otherwise noted.

All files and their content are released under the terms of the Artistic Licence 2.0, unless otherwise noted.

The operator of this repository shall not be held liable for offending content in pages linking to or linked from these page, nor does he endorse their content unless stated otherwise.