Merge branch 'feature/opt-list_untracked-a'

[code/vcsh.git] / doc / vcsh.1.ronn

diff --git a/doc/vcsh.1.ronn b/doc/vcsh.1.ronn
index f82a8776940167d6d13073906a7d743035c0f02c..2bf8a77ebd8c394d58a402e78b916af39ed4d197 100644 (file)
--- a/doc/vcsh.1.ronn
+++ b/doc/vcsh.1.ronn
@@ -5,7 +5,7 @@ vcsh(1) - Version Control System for $HOME - multiple Git repositories in $HOME
 
 `vcsh` [<options>] <command>
 
-`vcsh` clone <url> [<repo>]
+`vcsh` clone [-b <branch>] <url> [<repo>]
 
 `vcsh` delete <repo>
 
@@ -17,11 +17,9 @@ vcsh(1) - Version Control System for $HOME - multiple Git repositories in $HOME
 
 `vcsh` list
 
-`vcsh` list-tracked
+`vcsh` list-tracked [<repo>]
 
-`vcsh` list-tracked-by <repo>
-
-`vcsh` list-untracked [<-r>] [<repo>]
+`vcsh` list-untracked [<-a>] [<-r>] [<repo>]
 
 `vcsh` pull
 
@@ -88,6 +86,9 @@ an interactive user.
   If you need to clone a bundle of repositories, look into the
   `post-clone-retired` hook.
 
+  You can also use a single git repository with several branches. Use the `-b`
+  option to specify a branch at clone time, the default is `master`.
+
 * commit:
   Commit in all repositories
 
@@ -109,18 +110,25 @@ an interactive user.
 * list-tracked:
   List all files tracked by vcsh.
 
+  If you want to list files tracked by a specific repository, simply
+  append the repository's name last.
+
 * list-tracked-by:
   List files tracked by a repository.
 
+  This is a legacy command; you should use `list-tracked <repo>` instead.
+
 * list-untracked:
   List all files NOT tracked by vcsh.
 
+  `-a`: Show all files.
+  By default, the `git ls-files --exclude-standard` is called.
+
+  `-r`: Recursive mode.
   By default, the file list is shallow and stops at directory levels where
-  possible. If you prefer to get a list of all files, append `-r` for
-  recursive mode.
+  possible.
 
-  If you want to list files not tracked by a specific repository, simply
-  append the repository's name last.
+  `$repo`: List files not tracked by this specific repository.
 
 * pull:
   Pull from all vcsh remotes.
@@ -266,6 +274,24 @@ Available hooks are <pre-clone>, <post-clone>, <post-clone-retired>,
 If you need more, vcsh is trivial to patch, but please let upstream know so
 we can ship them by default.
 
+## OVERLAY SYSTEM
+
+`vcsh` also provides an overlay system. Similar to hooks, the recommended
+locations are <$XDG_CONFIG_HOME/vcsh/overlays-available> and
+<$XDG_CONFIG_HOME/vcsh/overlays-enabled>.
+
+Overlays follow the same rules as hooks and you are free to overwrite any
+and all functions. Same as hooks, you can use global or repository-specific
+overlays by using either <$VCSH_OVERLAY_D/$VCSH_COMMAND> or
+<$VCSH_OVERLAY_D/$VCSH_REPO_NAME.$VCSH_COMMAND>.
+
+Please note that nothing stops you from, e.g. overwriting `status()` in
+<$VCSH_OVERLAY_D/commit>. As the overlays will be sourced and you are
+replacing arbitrary functions, any and all features may stop working, or you
+may even lose data.
+
+You have been warned.
+
 ## DETAILED HOWTO AND FURTHER READING
 
 Manpages are often short and sometimes useless to glean best practices from.
@@ -315,7 +341,7 @@ This manpage and `vcsh` itself were written by Richard "RichiH" Hartmann.
 
 ## COPYRIGHT
 
-Copyright 2011-2013 Richard Hartmann <richih@debian.org>
+Copyright 2011-2015 Richard Hartmann <richih@debian.org>
 
 Licensed under the GNU GPL version 2 or higher.