README.md

   1 vcsh - manage and sync config files via git
   2
   3 # Index #
   4
   5 1. Introduction
   6 2. Overview
   7 3. Getting Started
   8 4. Usage
   9
  10 # 1 Introduction #
  11
  12 vcsh allows you to have several git repositories, all maintaining their working
  13 trees in $HOME without clobbering each other. That, in turn, means you can have
  14 one repository per config set (zsh, vim, ssh, etc), picking and choosing which
  15 configs you want to use on which machine.
  16
  17 vcsh was designed with [mr] [1] in mind so you might want to install that, as
  18 well.
  19
  20 Read INSTALL.md for detailed setup instructions.
  21
  22 The following overview will try to give you an idea of the use cases and
  23 advantages of vcsh. See sections 3 and 4 for detailed instructions and
  24 examples.
  25
  26 # 2 Overview
  27
  28 ## 2.1 Comparison to Other Solutions ##
  29
  30 Most people who decide to put their dotfiles under version control start with a
  31 **single repository in $HOME**, adding all their dotfiles (and possibly more)
  32 to it. This works, of course, but can become a nuisance as soon as you try to
  33 manage more than one host.
  34
  35 The next logical step is to create single-purpose repositories in, for example,
  36 ~/.dotfiles and to create **symbolic links in $HOME**. This gives you the
  37 flexibility to check out only certain repositories on different hosts. The
  38 downsides of this approach are the necessary manual steps of cloning and
  39 symlinking the individual repositories. It will probably become a nuisance when
  40 you try to manage more than two hosts.
  41
  42 **vcsh** takes this second approach one step further. It expects
  43 **single-purpose repositories** and stores them in a hidden directory (similar
  44 to ~/.dotfiles). However, it does not create symbolic links in $HOME; it puts
  45 the **actual files right into $HOME**.
  46
  47 Furthermore, by making use of [mr] [1], it makes it very easy to enable/disable
  48 and clone a large number of repositories. The use of mr is technically optional
  49 (see 3.4), but it will be an integral part of the proposed system that follows.
  50
  51 ## 2.2 Default Directory Layout ##
  52
  53 To illustrate, this is what a possible directory structure looks like.
  54
  55     $HOME
  56         |-- .config
  57         |   |-- mr
  58         |   |   |-- available.d
  59         |   |   |   |-- zsh.vcsh
  60         |   |   |   |-- gitconfigs.vcsh
  61         |   |   |   |-- lftp.vcsh
  62         |   |   |   |-- offlineimap.vcsh
  63         |   |   |   |-- s3cmd.vcsh
  64         |   |   |   |-- tmux.vcsh
  65         |   |   |   |-- vim.vcsh
  66         |   |   |   |-- vimperator.vcsh
  67         |   |   |   `-- snippets.git
  68         |   |   `-- config.d
  69         |   |       |-- zsh.vcsh        -> ../available.d/zsh.vcsh
  70         |   |       |-- gitconfigs.vcsh -> ../available.d/gitconfigs.vcsh
  71         |   |       |-- tmux.vcsh       -> ../available.d/tmux.vcsh
  72         |   |       `-- vim.vcsh        -> ../available.d/vim.vcsh
  73         |   `-- vcsh
  74         |       `-- repo.d
  75         |           |-- zsh.git  -----------+
  76         |           |-- gitconfigs.git      |
  77         |           |-- tmux.git            |
  78         |           `-- vim.git             |
  79         |-- [...]                           |
  80         |-- .zshrc   <----------------------+
  81         |-- .gitignore
  82         |-- .mrconfig
  83         `-- .mrtrust
  84
  85 ### available.d ###
  86
  87 The files you see in ~/.config/mr/available.d are mr configuration files that
  88 contain the commands to manage (checkout, update etc.) a single repository.
  89 vcsh repo configs end in .vcsh, git configs end in .git, etc. This is optional
  90 and your preference. For example, this is what a zsh.mrconfig with read-only
  91 access to my zshrc repo looks likes. I.e. in this specific example, push can
  92 not work.
  93
  94     [$HOME/.config/vcsh/repo.d/zsh.git]
  95     checkout = vcsh clone 'git://github.com/RichiH/zshrc.git'
  96     update   = vcsh run bash git pull
  97     push     = vcsh run bash git push
  98     status   = vcsh run bash git status
  99     gc       = vcsh run bash git gc
 100
 101 ### config.d ###
 102
 103 ~/.config/mr/available.d contains *all available* repositories. Only
 104 files/links present in mr/config.d, however, will be used by mr. That means
 105 that in this example, only the zsh, gitconfigs, tmux and vim repositories will
 106 be checked out. A simple `mr update` run in $HOME will clone or update those
 107 four repositories listed in config.d.
 108
 109 ### repo.d ###
 110
 111 ~/.config/vcsh/repo.d is the directory into which vcsh clones the git
 112 repositories. Since their working trees are configured to be in $HOME, the
 113 files contained in those repositories will be put in $HOME directly (see .zshrc
 114 above).
 115
 116 ### ~/.mrconfig ###
 117
 118 Finally, ~/.mrconfig will tie together all those single files which will allow
 119 you to conveniently run `mr up` etc. to manage all repositories. It looks like
 120 this:
 121
 122     [DEFAULT]
 123     jobs = 5
 124     include = cat ~/.config/mr/config.d/*
 125
 126
 127 vcsh will check if any file it would want to create exists. If it exists, vcsh
 128 will throw a warning and exit. Move away your old config and try again.
 129 Optionally, merge your local and your global configs afterwards and push with
 130 `vcsh run foo git push`.
 131
 132 ## 2.3 Moving into a New Host ##
 133
 134 To illustrate further, the following steps could move your desired
 135 configuration to a new host.
 136
 137 1. Clone the mr repository (containing available.d, config.d etc.); for
 138    example: `vcsh clone git://github.com/RichiH/vcsh_mr_template.git`
 139 2. Choose your repositories by linking them in config.d (or go with the default
 140    you may have already configured by adding symlinks to git).
 141 3. Run mr to clone the repositories: `cd; mr update`.
 142 4. Done.
 143
 144 Hopefully the above could help explain how this approach saves time by
 145
 146 1. making it easy to manage, clone and update a large number of repositories
 147    (thanks to mr) and
 148 2. making it unnecessary to create symbolic links in $HOME (thanks to vcsh).
 149
 150 If you want to give vcsh a try, follow the instructions below.
 151
 152 # 3 Getting Started #
 153
 154 Below, you will find a few different methods for setting up vcsh:
 155
 156 1. The Template Way
 157 2. The Steal-from-Template Way
 158 3. The Manual Way
 159
 160 ### 3.1 The Template Way ###
 161
 162 #### 3.1.1 Prerequisites ####
 163
 164 Make sure none of the following files and directories exist for your test
 165 (user). If they do, move them away for now:
 166
 167 * ~/.gitignore
 168 * ~/.mrconfig
 169 * ~/.config/mr/available.d/mr.vcsh
 170 * ~/.config/mr/available.d/zsh.vcsh
 171 * ~/.config/mr/config.d/mr.vcsh
 172 * ~/.config/vcsh/repo.d/mr.git/
 173
 174 All of the files are part of the template repository, the directory is where
 175 the template will be stored.
 176
 177     apt-get install mr               # this is optional, but highly recommended
 178
 179 #### 3.1.2 Clone the Template ####
 180
 181     mkdir -p ~/work/git
 182     cd !$
 183     git clone git://github.com/RichiH/vcsh.git vcsh
 184     cd vcsh
 185     ln -s vcsh /usr/local/bin        # or add it to your PATH
 186     cd
 187     vcsh clone git://github.com/RichiH/vcsh_mr_template.git mr.vcsh
 188
 189 #### 3.1.3 Enable Your Test Repository ####
 190
 191     mv ~/.zsh   ~/zsh.bak
 192     mv ~/.zshrc ~/zshrc.bak
 193     cd ~/.config/mr/config.d/
 194     ln -s ../available.d/zsh.vcsh .  # link, and thereby enable, the zsh repository
 195     cd
 196     mr up
 197
 198 #### 3.1.4 Set Up Your Own Repositories ####
 199
 200 Now, it's time to edit the template config and fill it with your own remotes:
 201
 202     vim .config/mr/available.d/mr.vcsh
 203     vim .config/mr/available.d/zsh.vcsh
 204
 205 And then create your own stuff:
 206
 207     vcsh init foo
 208     vcsh run foo git add -f bar baz quux
 209     vcsh run foo git remote add origin git://quuux
 210     vcsh run foo git commit
 211     vcsh run foo git push
 212
 213     cp .config/mr/available.d/mr.vcsh .config/mr/available.d/foo.vcsh
 214     vim .config/mr/available.d/foo.vcsh # add your own repo
 215
 216 Done!
 217
 218 ### 3.2 The Steal-from-Template Way ###
 219
 220 You're welcome to clone the example repository:
 221
 222     git clone git://github.com/RichiH/vcsh_mr_template.git
 223
 224 Look around in the clone. It should be reasonably simple to understand. If not,
 225 poke me, RichiH, on Freenode (query) or OFTC (#vcs-home).
 226
 227
 228 ### 3.3 The Manual Way ###
 229
 230 This is how my old setup procedure looked like. Adapt it to your own style or
 231 copy mine verbatim, either is fine.
 232
 233     # Create workspace
 234     mkdir -p ~/work/git
 235     cd !$
 236
 237     # Clone vcsh and make it available
 238     git clone git://github.com/RichiH/vcsh.git vcsh
 239     sudo ln -s ~/work/git/vcsh/vcsh /usr/bin/local
 240     hash -r
 241
 242 Grab my mr config. see below for details on how I set this up
 243
 244     vcsh clone ssh://<remote>/mr.git
 245     cd ~/.config/mr/config.d/
 246     ln -s ../available.d/* .
 247
 248
 249 mr is used to actually retrieve configs, etc
 250
 251     ~ % cat ~/.mrconfig
 252     [DEFAULT]
 253     include = cat ~/.config/mr/config.d/*
 254     ~ % echo $XDG_CONFIG_HOME
 255     /home/richih/.config
 256     ~ % ls $XDG_CONFIG_HOME/mr/available.d # random selection of my repos
 257     git-annex gitk.vcsh git.vcsh ikiwiki mr.vcsh reportbug.vcsh snippets.git wget.vcsh zsh.vcsh
 258     ~ %
 259     # then simply ln -s whatever you want on your local machine from
 260     # $XDG_CONFIG_HOME/mr/available.d to $XDG_CONFIG_HOME/mr/config.d
 261     ~ % cd
 262     ~ % mr -j 5 up
 263
 264 # 4 Usage #
 265
 266 ### 4.1 Keeping repositories Up-to-Date ###
 267
 268 This is the beauty of it all. Once you are set up, just run:
 269
 270     mr up
 271     mr push
 272
 273 Neat.
 274
 275 ### 4.1 Making Changes ###
 276
 277 After you have made some changes, for which you would normally use `git add`
 278 and `git commit`, use the vcsh wrapper (like above):
 279
 280     vcsh run foo git add -f bar baz quux
 281     vcsh run foo git commit
 282     vcsh run foo git push
 283
 284 By the way, you'll have to use -f/--force flag with git-add because all files
 285 will be ignored by default. This is to show you only useful output when running
 286 git-status. A fix for this problem is being worked on.
 287
 288 ### 4.3 Using vcsh without mr ###
 289
 290 vcsh encourages you to use mr. It helps you manage a large number of
 291 repositories by running the necessary vcsh commands for you. You may choose not
 292 to use mr, in which case you will have to run those commands manually or by
 293 other means.
 294
 295 #### A Few Examples ####
 296
 297 To initialize a new repository: `vcsh init zsh`
 298
 299 To clone a repository: `vcsh clone ssh://<remote>/zsh.git`
 300
 301 To interact with a repository, use the regular Git commands, but prepend them
 302 with `vcsh run $repository_name`. For example:
 303
 304     vcsh run zsh git status
 305     vcsh run zsh git add -f .zshrc
 306     vcsh run zsh git commit
 307
 308 Obviously, without mr keeping repositories up-to-date, it will have to be done
 309 manually. Alternatively, you could try something like this:
 310
 311     for repo in `vcsh list`; do
 312         vcsh run $repo git pull;
 313     done
 314
 315 ----------
 316
 317 mr can be found at: [http://kitenet.net/~joey/code/mr/][1]
 318
 319 [1]: http://kitenet.net/~joey/code/mr/ (http://kitenet.net/~joey/code/mr/)