X-Git-Url: https://git.madduck.net/code/vcsh.git/blobdiff_plain/8364333583ce45cc41c334a34d4793276f8bf691..refs/heads/docs-improvements:/README.md?ds=sidebyside

diff --git a/README.md b/README.md
index fce637b..8017d84 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,25 @@
-vcsh - manage and sync config files via git
+vcsh - manage config files in $HOME via fake bare git repositories
 
 # Index #
 
-1. Introduction
-2. Overview
-3. Getting Started
-4. Usage
+1. Contact
+2. Introduction
+3. Overview
+4. Getting Started
+5. Usage
 
-# 1 Introduction #
+# 1 Contact #
+
+There are several ways to get in touch with the author and a small but committed
+community around the general idea of version controlling your (digital) life.
+
+* IRC: #vcs-home on irc.oftc.net
+
+* Mailing list: http://lists.madduck.net/listinfo/vcs-home
+
+* Pull requests or issues on https://github.com/RichiH/vcsh
+
+# 2 Introduction #
 
 vcsh allows you to have several git repositories, all maintaining their working
 trees in $HOME without clobbering each other. That, in turn, means you can have
@@ -23,9 +35,14 @@ The following overview will try to give you an idea of the use cases and
 advantages of vcsh. See sections 3 and 4 for detailed instructions and
 examples.
 
-# 2 Overview
+## 2.1 Talks ##
+
+Some people found it useful to look at slides and videos explaining how vcsh works.
+They can all be found at [here](http://richardhartmann.de/talks/).
 
-## 2.1 Comparison to Other Solutions ##
+# 3 Overview
+
+## 3.1 Comparison to Other Solutions ##
 
 Most people who decide to put their dotfiles under version control start with a
 **single repository in $HOME**, adding all their dotfiles (and possibly more)
@@ -48,7 +65,7 @@ Furthermore, by making use of [mr] [1], it makes it very easy to enable/disable
 and clone a large number of repositories. The use of mr is technically optional
 (see 4.3), but it will be an integral part of the proposed system that follows.
 
-## 2.2 Default Directory Layout ##
+## 3.2 Default Directory Layout ##
 
 To illustrate, this is what a possible directory structure looks like.
 
@@ -71,6 +88,7 @@ To illustrate, this is what a possible directory structure looks like.
         |   |       |-- tmux.vcsh       -> ../available.d/tmux.vcsh
         |   |       `-- vim.vcsh        -> ../available.d/vim.vcsh
         |   `-- vcsh
+        |       |-- config
         |       `-- repo.d
         |           |-- zsh.git  -----------+
         |           |-- gitconfigs.git      |
@@ -78,13 +96,14 @@ To illustrate, this is what a possible directory structure looks like.
         |           `-- vim.git             |
         |-- [...]                           |
         |-- .zshrc   <----------------------+
-        |-- .gitignore
+        |-- .gitignore.d
+        |   `-- zsh
         |-- .mrconfig
         `-- .mrtrust
 
 ### available.d ###
 
-The files you see in $XDG_CONFIG_HOME/mr/available.d are mr configuration files
+The files you see in $XDG\_CONFIG\_HOME/mr/available.d are mr configuration files
 that contain the commands to manage (checkout, update etc.) a single
 repository. vcsh repo configs end in .vcsh, git configs end in .git, etc. This
 is optional and your preference. For example, this is what a zsh.vcsh
@@ -94,15 +113,18 @@ is for demonstration, only. Of course, you are more than welcome to clone from
 this repository and fork your own.
 
     [$XDG_CONFIG_HOME/vcsh/repo.d/zsh.git]
-    checkout = vcsh clone 'git://github.com/RichiH/zshrc.git' zsh
-    update   = vcsh run zsh git pull
-    push     = vcsh run zsh git push
-    status   = vcsh run zsh git status
-    gc       = vcsh run zsh git gc
+    checkout = vcsh clone 'git://github.com/RichiH/zshrc.git' $MR_REPO
+    push     = echo "Cannot push to read-only repo" >&2
+    #status   = vcsh run $MR_REPO git $MR_ACTION
+    #commit   = vcsh run $MR_REPO git $MR_ACTION
+    #gc       = vcsh run $MR_REPO git $MR_ACTION
+
+The commented lines are only necessary if you are using `mr` prior to version
+1.11. Starting with this version, `vcsh` support is properly integrated.
 
 ### config.d ###
 
-$XDG_CONFIG_HOME/mr/available.d contains *all available* repositories. Only
+$XDG\_CONFIG\_HOME/mr/available.d contains *all available* repositories. Only
 files/links present in mr/config.d, however, will be used by mr. That means
 that in this example, only the zsh, gitconfigs, tmux and vim repositories will
 be checked out. A simple `mr update` run in $HOME will clone or update those
@@ -116,11 +138,16 @@ this:
 
     [DEFAULT]
     jobs = 5
-    include = cat $XDG_CONFIG_HOME/mr/config.d/*
+    # The following line is only needed if your mr does not have vcsh support
+    # in core, that is version 1.10 or older. Check the file itself if you are
+    # unsure.
+    include = cat /usr/share/mr/vcsh
+    # Include all (enabled) configuration snippets (see above)
+    include = cat ${XDG_CONFIG_HOME:-$HOME/.config}/mr/config.d/*
 
 ### repo.d ###
 
-$XDG_CONFIG_HOME/vcsh/repo.d is the directory where all git repositories which
+$XDG\_CONFIG\_HOME/vcsh/repo.d is the directory where all git repositories which
 are under vcsh's control are located. Since their working trees are configured
 to be in $HOME, the files contained in those repositories will be put in $HOME
 directly.
@@ -132,17 +159,19 @@ will throw a warning and exit. Move away your old config and try again.
 Optionally, merge your local and your global configs afterwards and push with
 `vcsh run foo git push`.
 
-## 2.3 Moving into a New Host ##
+## 3.3 Moving into a New Host ##
 
 To illustrate further, the following steps could move your desired
 configuration to a new host.
 
 1. Clone the mr repository (containing available.d, config.d etc.); for
-   example: `vcsh clone git://github.com/RichiH/vcsh_mr_template.git`
+   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. Run mr to clone the repositories: `cd; mr update`.
-4. Done.
+3. Make sure the line 'include = cat /usr/share/mr/vcsh' in .mrconfig points
+   to an existing file. Check the file itself to see if the line is necessary.
+4. Run mr to clone the repositories: `cd; mr update`.
+5. Done.
 
 Hopefully the above could help explain how this approach saves time by
 
@@ -152,7 +181,7 @@ Hopefully the above could help explain how this approach saves time by
 
 If you want to give vcsh a try, follow the instructions below.
 
-# 3 Getting Started #
+# 4 Getting Started #
 
 Below, you will find a few different methods for setting up vcsh:
 
@@ -160,36 +189,67 @@ Below, you will find a few different methods for setting up vcsh:
 2. The Steal-from-Template Way
 3. The Manual Way
 
-### 3.1 The Template Way ###
+### 4.1 The Template Way ###
 
-#### 3.1.1 Prerequisites ####
+#### 4.1.1 Prerequisites ####
 
 Make sure none of the following files and directories exist for your test
 (user). If they do, move them away for now:
 
-* ~/.gitignore
+* ~/.gitignore.d
 * ~/.mrconfig
-* $XDG_CONFIG_HOME/mr/available.d/mr.vcsh
-* $XDG_CONFIG_HOME/mr/available.d/zsh.vcsh
-* $XDG_CONFIG_HOME/mr/config.d/mr.vcsh
-* $XDG_CONFIG_HOME/vcsh/repo.d/mr.git/
+* $XDG\_CONFIG\_HOME/mr/available.d/mr.vcsh
+* $XDG\_CONFIG\_HOME/mr/available.d/zsh.vcsh
+* $XDG\_CONFIG\_HOME/mr/config.d/mr.vcsh
+* $XDG\_CONFIG\_HOME/vcsh/repo.d/mr.git/
 
 All of the files are part of the template repository, the directory is where
 the template will be stored.
 
     apt-get install mr
 
-#### 3.1.2 Clone the Template ####
+#### 4.1.2 Install vcsh ####
+
+#### 4.1.2.1 Debian ####
+
+If you are using Debian Squeeze, you will need to enable backports
+
+    apt-get install vcsh
 
+#### 4.1.2.2 Arch Linux ####
+
+vcsh is availabe via [AUR](https://aur.archlinux.org/packages.php?ID=54164)
+and further documentation about the use of AUR is available
+[on Arch's wiki](https://wiki.archlinux.org/index.php/Arch_User_Repository).
+
+    cd /var/abs/local/
+    wget https://aur.archlinux.org/packages/vc/vcsh-git/vcsh-git.tar.gz
+    tar xfz vcsh-git.tar.gz
+    cd vcsh-git
+    makepkg -s
+    pacman -U vcsh*.pkg.tar.xz
+
+#### 4.1.2.3 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 !$
-    git clone git://github.com/RichiH/vcsh.git vcsh
+    git clone git://github.com/RichiH/vcsh.git
     cd vcsh
-    ln -s vcsh /usr/local/bin        # or add it to your PATH
+    ln -s vcsh /usr/local/bin                       # or add it to your PATH
     cd
-    vcsh clone git://github.com/RichiH/vcsh_mr_template.git mr.vcsh
 
-#### 3.1.3 Enable Your Test Repository ####
+#### 4.1.3 Clone the Template ####
+
+    vcsh clone git://github.com/RichiH/vcsh_mr_template.git mr
+
+#### 4.1.4 Enable Your Test Repository ####
 
     mv ~/.zsh   ~/zsh.bak
     mv ~/.zshrc ~/zshrc.bak
@@ -198,7 +258,7 @@ the template will be stored.
     cd
     mr up
 
-#### 3.1.4 Set Up Your Own Repositories ####
+#### 4.1.5 Set Up Your Own Repositories ####
 
 Now, it's time to edit the template config and fill it with your own remotes:
 
@@ -218,17 +278,19 @@ And then create your own stuff:
 
 Done!
 
-### 3.2 The Steal-from-Template Way ###
+### 4.2 The Steal-from-Template Way ###
 
 You're welcome to clone the example repository:
 
-    git clone git://github.com/RichiH/vcsh_mr_template.git
+    vcsh clone git://github.com/RichiH/vcsh_mr_template.git mr
+    # make sure 'include = cat /usr/share/mr/vcsh' points to an exiting file
+    vim .mrconfig
 
 Look around in the clone. It should be reasonably simple to understand. If not,
 poke me, RichiH, on Freenode (query) or OFTC (#vcs-home).
 
 
-### 3.3 The Manual Way ###
+### 4.3 The Manual Way ###
 
 This is how my old setup procedure looked like. Adapt it to your own style or
 copy mine verbatim, either is fine.
@@ -253,6 +315,8 @@ mr is used to actually retrieve configs, etc
 
     ~ % cat ~/.mrconfig
     [DEFAULT]
+    # adapt /usr/share/mr/vcsh to your system if needed
+    include = cat /usr/share/mr/vcsh
     include = cat $XDG_CONFIG_HOME/mr/config.d/*
     ~ % echo $XDG_CONFIG_HOME
     /home/richih/.config
@@ -264,9 +328,9 @@ mr is used to actually retrieve configs, etc
     ~ % cd
     ~ % mr -j 5 up
 
-# 4 Usage #
+# 5 Usage #
 
-### 4.1 Keeping repositories Up-to-Date ###
+### 5.1 Keeping repositories Up-to-Date ###
 
 This is the beauty of it all. Once you are set up, just run:
 
@@ -275,7 +339,7 @@ This is the beauty of it all. Once you are set up, just run:
 
 Neat.
 
-### 4.1 Making Changes ###
+### 5.1 Making Changes ###
 
 After you have made some changes, for which you would normally use `git add`
 and `git commit`, use the vcsh wrapper (like above):
@@ -288,7 +352,7 @@ By the way, you'll have to use -f/--force flag with git-add because all files
 will be ignored by default. This is to show you only useful output when running
 git-status. A fix for this problem is being worked on.
 
-### 4.3 Using vcsh without mr ###
+### 5.3 Using vcsh without mr ###
 
 vcsh encourages you to use [mr] [1]. It helps you manage a large number of
 repositories by running the necessary vcsh commands for you. You may choose not