-Richard Hartmann <richih.mailinglist@gmail.com> <richih+github.com@richih.org>
+Richard Hartmann <richih@debian.org> <richih+github.com@richih.org>
+Richard Hartmann <richih@debian.org> <richih.mailinglist@gmail.com>
Alexander Skurikhin <a.skurihin@gmail.com> <a.skurihin@gmail.com>
martin f. krafft <madduck@madduck.net>
Alessandro Ghedini <alessandro@ghedini.me>
Valentin Haenel <valentin.haenel@gmx.de>
-Richard Hartmann <richih.mailinglist@gmail.com>
+Richard Hartmann <richih@debian.org>
mek-apelsin <mek@pels.in>
Dieter Plaetinck <dieter@plaetinck.be>
Corey Quinn <corey@sequestered.net>
# Index
-1. [Introduction](#introduction)
-2. [30 second howto](#30-second-howto)
-3. [Overview](#overview)
-4. [Getting Started](#getting-started)
-5. [Usage Exmaples](#usage-examples)
+1. [30 second howto](#30-second-howto)
+2. [Introduction](#introduction)
+3. [Usage Exmaples](#usage-examples)
+4. [Overview](#overview)
+5. [Getting Started](#getting-started)
6. [Contact](#contact)
+# 30 second howto
+
+While it may appear that there's an overwhelming amount of documentation and
+while the explanation of the concepts behind `vcsh` needs to touch a few gory
+details of `git` internals, getting started with `vcsh` is extremely simple.
+
+Let's say you want to version control your `vim` configuration:
+
+ vcsh init vim
+ vcsh vim add ~/.vimrc ~/.vim
+ vcsh vim commit -m 'Initial commit of my Vim configuration'
+ # optionally push your files to a remote
+ vcsh vim remote add origin <remote>
+ vcsh vim push -u origin master
+ # from now on you can push additional commits like this
+ vcsh vim push
+
+If all that looks a _lot_ like standard `git`, that's no coincidence; it's
+a design feature.
+
+
# Introduction
-[vcsh][vcsh] allows you to maintain several git repositories in one single
+[vcsh][vcsh] allows you to maintain several Git repositories in one single
directory. They all maintain their working trees without clobbering each other
-or interfering otherwise. By default, all git repositories maintained via
-`vcsh` are stored in `$HOME` but you can override this setting if you want to.
+or interfering otherwise. By default, all Git repositories maintained via
+`vcsh` store the actual files in `$HOME` but you can override this setting if
+you want to.
All this means that you can have one repository per application or application
family, i.e. `zsh`, `vim`, `ssh`, etc. This, in turn, allows you to clone
custom sets of configurations onto different machines or even for different
or available to root and you may want to maintain different configuration for
`ssh` on your personal and your work machines.
-`vcsh` was designed with [mr][mr], a tool to manage Multiple Repositories, in
-mind and the two integrate very nicely. `mr` has native support for `vcsh`
-repositories and to `vcsh`, `mr` is just another configuration to track.
-This make setting up any new machine a breeze. It takes literally less than
-five minutes to go from standard installation to fully set up system
-
-A lot of modern UNIX-based systems offer pacakges for `vcsh`. In case yours
+A lot of modern UNIX-based systems offer packages for `vcsh`. In case yours
does not read `INSTALL.md` for install instructions or `PACKAGING.md` to create
a package, yourself. If you do end up packaging `vcsh` please let us know so we
can give you your own packaging branch in the upstream repository.
## Talks
Some people found it useful to look at slides and videos explaining how `vcsh`
-works instead of working through the docs, first.
-They can all be found [on the author's talk page][talks].
+works instead of working through the docs.
+All slides, videos, and further information can be found
+[on the author's talk page][talks].
-# 30 second howto
+# Usage Examples
-While it may appear that there's an overwhelming amount of documentation and
-while the explanation of the concepts behind `vcsh` needs to touch a few gory
-details of `git` internals, getting started with `vcsh` is extremely simple.
+There are three different ways to interact with `vcsh` repositories; this
+section will only show the simplest and easiest way.
+Certain more advanced use cases require the other two ways, but don't worry
+about this for now. If you never even bother playing with the other two
+modes you will still be fine.
+`vcsh enter` and `vcsh run` will be covered in later sections.
-Let's say you want to version control your `vim` configuration:
+
+## Initialize a new repository called "vim"
vcsh init vim
+
+## Clone an existing repository
+
+ vcsh clone <remote> <repository_name>
+
+## Add files to repository "vim"
+
vcsh vim add ~/.vimrc ~/.vim
- vcsh vim commit -m 'Initial commit of my Vim configuration'
- # optionally push your files to a remote
+ vcsh vim commit -m 'Update Vim configuration'
+
+## Add a remote for repository "vim"
+
vcsh vim remote add origin <remote>
- vcsh vim push -u origin master
- # from now on you can push additional commits like this
+ vcsh vim push origin master:master
+ vcsh vim branch --track master origin/master
+
+## Push to remote of repository "vim"
+
vcsh vim push
-If all that looks a _lot_ like standard `git`, that's no coincidence; it's
-a design feature.
+## Pull from remote of repository "vim"
+
+ vcsh vim pull
+## Show status of changed files in all repositories
+
+ vcsh status
+
+## Pull from all repositories
+
+ vcsh pull
+
+## Push to all repositories
+
+ vcsh push
# Overview
takes care of pulling in and pushing out new data for a variety of version
control systems.
+`vcsh` was designed with [mr][mr], a tool to manage Multiple Repositories, in
+mind and the two integrate very nicely. `mr` has native support for `vcsh`
+repositories and to `vcsh`, `mr` is just another configuration to track.
+This make setting up any new machine a breeze. It takes literally less than
+five minutes to go from standard installation to fully set up system
-The last logical step is to maintain all those new repositores with an automated
-tool instead of tracking them by hand.
This is where `mr` comes in. While the use of `mr` is technically
optional, but it will be an integral part of the proposed system that follows.
this:
[DEFAULT]
- jobs = 5
- # Use if your mr does not have vcsh support in mainline, yet
- include = cat /usr/share/mr/vcsh
include = cat ${XDG_CONFIG_HOME:-$HOME/.config}/mr/config.d/*
### repo.d
example: `vcsh clone git://github.com/RichiH/vcsh_mr_template.git mr`
2. Choose your repositories by linking them in config.d (or go with the default
you may have already configured by adding symlinks to git).
-3. Make sure the line 'include = cat /usr/share/mr/vcsh' in .mrconfig points
- to an existing file
-4. Run mr to clone the repositories: `cd; mr update`.
-5. Done.
+3. Run mr to clone the repositories: `cd; mr update`.
+4. Done.
Hopefully the above could help explain how this approach saves time by
#### From source
-If your version of mr is older than version 1.07, make sure to put
-
- include = cat /usr/share/mr/vcsh
-
-into your .mrconfig .
-
# choose a location for your checkout
- cd $HOME
mkdir -p ~/work/git
+ cd ~/work/git
git clone git://github.com/RichiH/vcsh.git
cd vcsh
- ln -s vcsh /usr/local/bin # or add it to your PATH
+ sudo ln -s vcsh /usr/local/bin # or add it to your PATH
cd
#### Clone the Template
~ % mr -j 5 up
-# Usage Examples
-
-All examples in this section will use the short form of `vcsh` which is the
-simplest way to interface with it. If you don't know what that means simply
-ignore this fact for now and follow the examples.
-
-## Initialize a new repository "vim"
-
- vcsh init vim
-
-## Clone an existing repository
-
- vcsh clone <remote> <repository_name>
-
-## Add files to repository "vim"
-
- vcsh vim add ~/.vimrc ~/.vim
- vcsh vim commit -m 'Update Vim configuration'
-
-## Add a remote for repository "vim"
-
- vcsh vim remote add origin <remote>
- vcsh vim push origin master:master
- vcsh vim branch --track master origin/master
-
-## Push to remote of repository "vim"
-
- vcsh vim push
-
-## Pull from remote of repository "vim"
-
- vcsh vim pull
-
-
# mr usage ; will be factored out & rewritten
### Keeping repositories Up-to-Date
+2013-08-29 Richard Hartmann <richih.mailinglist@gmail.com>
+
+ * Release 1.20130829
+ * Add support for `vcsh commit`
+ * Add support for `vcsh status <repo>`
+ * Add pre-/post-init hooks
+ * Documentation improvements
+ * Minor cleanups
+
+2013-07-24 Richard Hartmann <richih.mailinglist@gmail.com>
+
+ * Release 1.20130724
+ * Add support for `vcsh status`
+ * Improve output of `vcsh pull`
+ * Improve output of `vcsh push`
+ * Minor documentation improvements
+
+2013-07-23 Richard Hartmann <richih.mailinglist@gmail.com>
+
+ * Release 1.20130723
+ * Support $VCSH_GITIGNORE == none
+ * Documentation improvements,
+ * Improved zsh completion
+ * Add support for `vcsh pull`
+ * Add support for `vcsh push`
+ * Add retire() to tear down vcsh ENV
+ * Add clone hooks, including one witout vcsh ENV to
+ allow subsequent cloning of other repos
+ * Fix `vcsh rename`
+ * Improve general code robustness
+
2013-06-14 Richard Hartmann <richih.mailinglist@gmail.com>
* Release 1.20130614
* post-command
* pre-enter
* post-enter
+* pre-init
+* post-init
* pre-pull
* post-pull
* pre-push
* post-run
* pre-upgrade
* post-upgrade
+
+If you write any interesting or useful hooks, please send them upstream
+so they can be included in an examples section.
`vcsh` run <repo> <shell command>
+`vcsh` status [<repo>]
+
`vcsh` upgrade <repo>
`vcsh` version
If you need to clone a bundle of repositories, look into the
`post-clone-retired` hook.
+* commit:
+ Commit in all repositories
+
* delete:
Delete an existing repository.
This is needed to support mr and other scripts properly and of no concern to
an interactive user.
+* status:
+ Show statuses of all/one vcsh repositories.
+
* upgrade:
Upgrade repository to currently recommended settings.
Interesting knobs you can turn:
* <$VCSH_GITIGNORE>:
- Can be <exact>, <recursive>, or <none>.
+ Can be <exact>, <none>, or <recursive>.
<exact> will seed the repo-specific ignore file with all file and directory
names which `git ls-files` returns.
+ <none> will not write any ignore file.
+
<recursive> will descend through all directories recursively additionally to
the above.
- <none> will not write any ignore file.
-
Defaults to <exact>.
Less interesting knobs you could turn:
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-upgrade>, and <post-upgrade>. If you need more, vcsh is trivial to patch,
-but please let upstream know so we can ship them by default.
+Available hooks are <pre-clone>, <post-clone>, <post-clone-retired>,
+<pre-command>, <post-command>, <pre-enter>, <post-enter>, <pre-init>,
+<post-init>, <pre-pull>, <post-pull>, <pre-push>, <post-push>, <pre-run>,
+<post-run>, <pre-upgrade>, and <post-upgrade>.
+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
## COPYRIGHT
-Copyright 2011-2013 Richard Hartmann <richih.mailinglist@gmail.com>
+Copyright 2011-2013 Richard Hartmann <richih@debian.org>
Licensed under the GNU GPL version 2 or higher.
#!/bin/sh
# This program is licensed under the GNU GPL version 2 or later.
-# (c) Richard "RichiH" Hartmann <richih.mailinglist@gmail.com>, 2011-2013
+# (c) Richard "RichiH" Hartmann <richih@debian.org>, 2011-2013
# For details, see LICENSE. To submit patches, you have to agree to
# license your code under the GNU GPL version 2 or later.
# While the following is not legally binding, the author would like to
# explain the choice of GPLv2+ over GPLv3+.
# The author prefers GPLv3+ over GPLv2+ but feels it's better to maintain
-# full compatibility's with git. In case git ever changes its licensing terms,
+# full compatibility's with Git. In case Git ever changes its licensing terms,
# which is admittedly extremely unlikely to the point of being impossible,
# this software will most likely follow suit.
}
SELF=$(basename $0)
-VERSION='1.20130614'
+VERSION='1.20130829'
fatal() {
echo "$SELF: fatal: $1" >&2
if [ "$1" = '-d' ] || [ "$1" = '--debug' ]; then
set -vx
VCSH_DEBUG=1
+ echo "debug mode on"
echo "$SELF $VERSION"
elif [ "$1" = '-v' ];then
VCSH_VERBOSE=1
+ echo "verbose mode on"
echo "$SELF $VERSION"
elif [ "$1" = '-c' ];then
VCSH_OPTION_CONFIG=$OPTARG
commands:
clone <remote> \\
[<repo>] Clone from an existing repository
+ commit Commit in all repositories
delete <repo> Delete an existing repository
enter <repo> Enter repository; spawn new instance of \$SHELL
help Display this help text
<newname> Rename repository
run <repo> \\
<command> Use this repository
+ status [<repo>] Show statuses of all/one vcsh repositories
upgrade <repo> Upgrade repository to currently recommended settings
version Print version information
which <substring> Find substring in name of any tracked file
hook post-clone-retired
}
+commit() {
+ hook pre-commit
+ for VCSH_REPO_NAME in $(list); do
+ echo "$VCSH_REPO_NAME: "
+ export GIT_DIR="$VCSH_REPO_D/$VCSH_REPO_NAME.git"
+ use
+ git commit --untracked-files=no --quiet
+ echo
+ done
+ hook post-commit
+}
+
delete() {
cd "$VCSH_BASE" || fatal "could not enter '$VCSH_BASE'" 11
use
}
init() {
+ hook pre-init
[ ! -e "$GIT_DIR" ] || fatal "'$GIT_DIR' exists" 10
mkdir -p "$VCSH_BASE" || fatal "could not create '$VCSH_BASE'" 50
cd "$VCSH_BASE" || fatal "could not enter '$VCSH_BASE'" 11
git init
upgrade
+ hook post-init
}
list() {
export GIT_DIR="$VCSH_REPO_D/$VCSH_REPO_NAME.git"
use
git pull
+ echo
done
hook post-pull
}
export GIT_DIR="$VCSH_REPO_D/$VCSH_REPO_NAME.git"
use
git push
+ echo
done
hook post-push
}
hook post-run
}
+status() {
+ if [ ! "x$VCSH_REPO_NAME" = "x" ]; then
+ export GIT_DIR="$VCSH_REPO_D/$VCSH_REPO_NAME.git"
+ use
+ git status --short --untracked-files='no'
+ else
+ for VCSH_REPO_NAME in $(list); do
+ echo "$VCSH_REPO_NAME:"
+ export GIT_DIR="$VCSH_REPO_D/$VCSH_REPO_NAME.git"
+ use
+ git status --short --untracked-files='no'
+ echo
+ done
+ fi
+}
+
upgrade() {
hook pre-upgrade
# fake-bare repositories are not bare, actually. Set this to false
fatal "could not move '$tempfile' to '$VCSH_BASE/.gitignore.d/$VCSH_REPO_NAME'" 53
}
-if [ ! "x$VCSH_GITIGNORE" = 'xexact' ] && [ ! "x$VCSH_GITIGNORE" = 'xrecursive' ] && [ ! "x$VCSH_GITIGNORE" = 'xnone' ]; then
- fatal "'\$VCSH_GITIGNORE' must equal 'exact', 'recursive', or 'none'" 1
+if [ ! "x$VCSH_GITIGNORE" = 'xexact' ] && [ ! "x$VCSH_GITIGNORE" = 'xnone' ] && [ ! "x$VCSH_GITIGNORE" = 'xrecursive' ]; then
+ fatal "'\$VCSH_GITIGNORE' must equal 'exact', 'none', or 'recursive'" 1
fi
if [ "$1" = 'clone' ]; then
[ "$VCSH_COMMAND" = 'rename' ] && { export VCSH_REPO_NAME_NEW="$3";
export GIT_DIR_NEW="$VCSH_REPO_D/$VCSH_REPO_NAME_NEW.git"; }
[ "$VCSH_COMMAND" = 'run' ] && shift 2
-elif [ "$1" = 'list' ] ||
+elif [ "$1" = 'commit' ] ||
+ [ "$1" = 'list' ] ||
[ "$1" = 'list-tracked' ] ||
[ "$1" = 'pull' ] ||
[ "$1" = 'push' ]; then
export VCSH_COMMAND="$1"
+elif [ "$1" = 'status' ]; then
+ export VCSH_COMMAND="$1"
+ export VCSH_REPO_NAME="$2"
elif [ -n "$2" ]; then
export VCSH_COMMAND='run'
export VCSH_REPO_NAME="$1"
if [ -e "$check_directory" ]; then
fatal "'$check_directory' exists but is not a directory" 13
else
- info "attempting to create '$check_directory'"
+ verbose "attempting to create '$check_directory'"
mkdir -p "$check_directory" || fatal "could not create '$check_directory'" 50
fi
fi
projects / code / vcsh.git / commitdiff