X-Git-Url: https://git.madduck.net/code/vcsh.git/blobdiff_plain/8364333583ce45cc41c334a34d4793276f8bf691..80ebb8dcdf12f32873670c8adcdd8d49ca2c7b01:/README.md

diff --git a/README.md b/README.md
index fce637b..5257753 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,9 @@ 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
+# 3 Overview
 
-## 2.1 Comparison to Other Solutions ##
+## 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 +60,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 +83,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 +91,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
@@ -102,7 +116,7 @@ this repository and fork your own.
 
 ### 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 +130,11 @@ this:
 
     [DEFAULT]
     jobs = 5
-    include = cat $XDG_CONFIG_HOME/mr/config.d/*
+    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 +146,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
+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 +168,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 +176,38 @@ 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 Clone the Template ####
 
+    cd $HOME
     mkdir -p ~/work/git
-    cd !$
     git clone git://github.com/RichiH/vcsh.git vcsh
+    # make sure 'include = cat /usr/share/mr/vcsh' points to an exiting file
+    vim .mrconfig
     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
+    vcsh clone git://github.com/RichiH/vcsh_mr_template.git mr
 
-#### 3.1.3 Enable Your Test Repository ####
+#### 4.1.3 Enable Your Test Repository ####
 
     mv ~/.zsh   ~/zsh.bak
     mv ~/.zshrc ~/zshrc.bak
@@ -198,7 +216,7 @@ the template will be stored.
     cd
     mr up
 
-#### 3.1.4 Set Up Your Own Repositories ####
+#### 4.1.4 Set Up Your Own Repositories ####
 
 Now, it's time to edit the template config and fill it with your own remotes:
 
@@ -218,17 +236,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 +273,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 +286,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 +297,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 +310,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