]> git.madduck.net Git - code/vcsh.git/blob - README.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

a7568561c1f17c0ec7dfcc8ef4f5b876078aba45
[code/vcsh.git] / README.md
1 vcsh - Version Control System for $HOME - multiple Git repositories in $HOME
2
3
4 # Index
5
6 1. [30 second howto](#30-second-howto)
7 2. [Introduction](#introduction)
8 3. [Usage Exmaples](#usage-examples)
9 4. [Overview](#overview)
10 5. [Getting Started](#getting-started)
11 6. [Contact](#contact)
12
13
14 # 30 second howto
15
16 While it may appear that there's an overwhelming amount of documentation and
17 while the explanation of the concepts behind `vcsh` needs to touch a few gory
18 details of `git` internals, getting started with `vcsh` is extremely simple.
19
20 Let's say you want to version control your `vim` configuration:
21
22     vcsh init vim
23     vcsh vim add ~/.vimrc ~/.vim
24     vcsh vim commit -m 'Initial commit of my Vim configuration'
25     # optionally push your files to a remote
26     vcsh vim remote add origin <remote>
27     vcsh vim push -u origin master
28     # from now on you can push additional commits like this
29     vcsh vim push
30
31 If all that looks a _lot_ like standard `git`, that's no coincidence; it's
32 a design feature.
33
34
35 # Introduction
36
37 [vcsh][vcsh] allows you to maintain several Git repositories in one single
38 directory. They all maintain their working trees without clobbering each other
39 or interfering otherwise. By default, all Git repositories maintained via
40 `vcsh` store the actual files in `$HOME` but you can override this setting if
41 you want to.
42 All this means that you can have one repository per application or application
43 family, i.e. `zsh`, `vim`, `ssh`, etc. This, in turn, allows you to clone
44 custom sets of configurations onto different machines or even for different
45 users; picking and mixing which configurations you want to use where.
46 For example, you may not need to have your `mplayer` configuration on a server
47 or available to root and you may want to maintain different configuration for
48 `ssh` on your personal and your work machines.
49
50 A lot of modern UNIX-based systems offer pacakges for `vcsh`. In case yours
51 does not read `INSTALL.md` for install instructions or `PACKAGING.md` to create
52 a package, yourself. If you do end up packaging `vcsh` please let us know so we
53 can give you your own packaging branch in the upstream repository.
54
55 ## Talks
56
57 Some people found it useful to look at slides and videos explaining how `vcsh`
58 works instead of working through the docs.
59 All slides, videos, and further information can be found
60 [on the author's talk page][talks].
61
62
63 # Usage Examples
64
65 There are three different ways to interact with `vcsh` repositories; this
66 section will only show the simplest and easiest way.
67 Certain more advanced use cases require the other two ways, but don't worry
68 about this for now. If you never ewen bother playing with the other two
69 modes you will still be fine.
70 `vcsh enter` and `vcsh run`  will be covered in later sections.
71
72
73 ## Initialize a new repository called "vim"
74
75     vcsh init vim
76
77 ## Clone an existing repository
78
79     vcsh clone <remote> <repository_name>
80
81 ## Add files to repository "vim"
82
83     vcsh vim add ~/.vimrc ~/.vim
84     vcsh vim commit -m 'Update Vim configuration'
85
86 ## Add a remote for repository "vim"
87
88     vcsh vim remote add origin <remote>
89     vcsh vim push origin master:master
90     vcsh vim branch --track master origin/master
91
92 ## Push to remote of repository "vim"
93
94     vcsh vim push
95
96 ## Pull from remote of repository "vim"
97
98     vcsh vim pull
99
100 ## Show status of changed files in all repositories
101
102     vcsh status
103
104 ## Pull from all repositories
105
106     vcsh pull
107
108 ## Push to all repositories
109
110     vcsh push
111
112 # Overview
113
114 ## From zero to vcsh
115
116 You put a lot of effort into your configuration and want to both protect and
117 distribute this configuration.
118
119 Most people who decide to put their dotfiles under version control start with a
120 single repository in `$HOME`, adding all their dotfiles (and possibly more)
121 to it. This works, of course, but can become a nuisance as soon as you try to
122 manage more than one host.
123
124 The next logical step is to create single-purpose repositories in, for example,
125 `~/.dotfiles` and to create symbolic links into `$HOME`. This gives you the
126 flexibility to check out only certain repositories on different hosts. The
127 downsides of this approach are the necessary manual steps of cloning and
128 symlinking the individual repositories.
129
130 `vcsh` takes this approach one step further. It enables single-purpose
131 repositories and stores them in a hidden directory. However, it does not create
132 symbolic links in `$HOME`; it puts the actual files right into `$HOME`.
133
134 As `vcsh` allows you to put an arbitrary number of distinct repositories into
135 your `$HOME`, you will end up with a lot of repositories very quickly.
136
137 To manage both `vcsh` and other repositories, we suggest using [mr](mr). `mr`
138 takes care of pulling in and pushing out new data for a variety of version
139 control systems.
140
141 `vcsh` was designed with [mr][mr], a tool to manage Multiple Repositories, in
142 mind and the two integrate very nicely. `mr` has native support for `vcsh`
143 repositories and to `vcsh`, `mr` is just another configuration to track.
144 This make setting up any new machine a breeze. It takes literally less than
145 five minutes to go from standard installation to fully set up system
146
147 This is where `mr` comes in. While the use of `mr` is technically
148 optional, but it will be an integral part of the proposed system that follows.
149
150 ## Default Directory Layout
151
152 To illustrate, this is what a possible directory structure looks like.
153
154     $HOME
155         |-- $XDG_CONFIG_HOME (defaults to $HOME/.config)
156         |   |-- mr
157         |   |   |-- available.d
158         |   |   |   |-- zsh.vcsh
159         |   |   |   |-- gitconfigs.vcsh
160         |   |   |   |-- lftp.vcsh
161         |   |   |   |-- offlineimap.vcsh
162         |   |   |   |-- s3cmd.vcsh
163         |   |   |   |-- tmux.vcsh
164         |   |   |   |-- vim.vcsh
165         |   |   |   |-- vimperator.vcsh
166         |   |   |   `-- snippets.git
167         |   |   `-- config.d
168         |   |       |-- zsh.vcsh        -> ../available.d/zsh.vcsh
169         |   |       |-- gitconfigs.vcsh -> ../available.d/gitconfigs.vcsh
170         |   |       |-- tmux.vcsh       -> ../available.d/tmux.vcsh
171         |   |       `-- vim.vcsh        -> ../available.d/vim.vcsh
172         |   `-- vcsh
173         |       |-- config
174         |       `-- repo.d
175         |           |-- zsh.git  -----------+
176         |           |-- gitconfigs.git      |
177         |           |-- tmux.git            |
178         |           `-- vim.git             |
179         |-- [...]                           |
180         |-- .zshrc   <----------------------+
181         |-- .gitignore.d
182         |   `-- zsh
183         |-- .mrconfig
184         `-- .mrtrust
185
186 ### available.d
187
188 The files you see in $XDG\_CONFIG\_HOME/mr/available.d are mr configuration files
189 that contain the commands to manage (checkout, update etc.) a single
190 repository. vcsh repo configs end in .vcsh, git configs end in .git, etc. This
191 is optional and your preference. For example, this is what a zsh.vcsh
192 with read-only access to my zshrc repo looks likes. I.e. in this specific
193 example, push can not work as you will be using the author's repository. This
194 is for demonstration, only. Of course, you are more than welcome to clone from
195 this repository and fork your own.
196
197     [$XDG_CONFIG_HOME/vcsh/repo.d/zsh.git]
198     checkout = vcsh clone 'git://github.com/RichiH/zshrc.git' zsh
199     update   = vcsh run zsh git pull
200     push     = vcsh run zsh git push
201     status   = vcsh run zsh git status
202     gc       = vcsh run zsh git gc
203
204 ### config.d
205
206 $XDG\_CONFIG\_HOME/mr/available.d contains *all available* repositories. Only
207 files/links present in mr/config.d, however, will be used by mr. That means
208 that in this example, only the zsh, gitconfigs, tmux and vim repositories will
209 be checked out. A simple `mr update` run in $HOME will clone or update those
210 four repositories listed in config.d.
211
212 ### ~/.mrconfig
213
214 Finally, ~/.mrconfig will tie together all those single files which will allow
215 you to conveniently run `mr up` etc. to manage all repositories. It looks like
216 this:
217
218     [DEFAULT]
219     jobs = 5
220     # Use if your mr does not have vcsh support in mainline, yet
221     include = cat /usr/share/mr/vcsh
222     include = cat ${XDG_CONFIG_HOME:-$HOME/.config}/mr/config.d/*
223
224 ### repo.d
225
226 $XDG\_CONFIG\_HOME/vcsh/repo.d is the directory where all git repositories which
227 are under vcsh's control are located. Since their working trees are configured
228 to be in $HOME, the files contained in those repositories will be put in $HOME
229 directly.
230 Of course, [mr] [mr] will work with this layout if configured according to this
231 document (see above).
232
233 vcsh will check if any file it would want to create exists. If it exists, vcsh
234 will throw a warning and exit. Move away your old config and try again.
235 Optionally, merge your local and your global configs afterwards and push with
236 `vcsh run foo git push`.
237
238 ## Moving into a New Host
239
240 To illustrate further, the following steps could move your desired
241 configuration to a new host.
242
243 1. Clone the mr repository (containing available.d, config.d etc.); for
244    example: `vcsh clone git://github.com/RichiH/vcsh_mr_template.git mr`
245 2. Choose your repositories by linking them in config.d (or go with the default
246    you may have already configured by adding symlinks to git).
247 3. Make sure the line 'include = cat /usr/share/mr/vcsh' in .mrconfig points
248    to an existing file
249 4. Run mr to clone the repositories: `cd; mr update`.
250 5. Done.
251
252 Hopefully the above could help explain how this approach saves time by
253
254 1. making it easy to manage, clone and update a large number of repositories
255    (thanks to mr) and
256 2. making it unnecessary to create symbolic links in $HOME (thanks to vcsh).
257
258 If you want to give vcsh a try, follow the instructions below.
259
260
261 # Getting Started
262
263 Below, you will find a few different methods for setting up vcsh:
264
265 1. The Template Way
266 2. The Steal-from-Template Way
267 3. The Manual Way
268
269 ### The Template Way
270
271 #### Prerequisites
272
273 Make sure none of the following files and directories exist for your test
274 (user). If they do, move them away for now:
275
276 * ~/.gitignore.d
277 * ~/.mrconfig
278 * $XDG\_CONFIG\_HOME/mr/available.d/mr.vcsh
279 * $XDG\_CONFIG\_HOME/mr/available.d/zsh.vcsh
280 * $XDG\_CONFIG\_HOME/mr/config.d/mr.vcsh
281 * $XDG\_CONFIG\_HOME/vcsh/repo.d/mr.git/
282
283 All of the files are part of the template repository, the directory is where
284 the template will be stored.
285
286     apt-get install mr
287
288 #### Install vcsh
289
290 #### Debian
291
292 If you are using Debian Squeeze, you will need to enable backports
293
294     apt-get install vcsh
295
296 #### Arch Linux
297
298 vcsh is availabe via [AUR](https://aur.archlinux.org/packages.php?ID=54164)
299 and further documentation about the use of AUR is available
300 [on Arch's wiki](https://wiki.archlinux.org/index.php/Arch_User_Repository).
301
302     cd /var/abs/local/
303     wget https://aur.archlinux.org/packages/vc/vcsh-git/vcsh-git.tar.gz
304     tar xfz vcsh-git.tar.gz
305     cd vcsh-git
306     makepkg -s
307     pacman -U vcsh*.pkg.tar.xz
308
309 #### From source
310
311 If your version of mr is older than version 1.07, make sure to put
312
313     include = cat /usr/share/mr/vcsh
314
315 into your .mrconfig .
316
317     # choose a location for your checkout
318     cd $HOME
319     mkdir -p ~/work/git
320     git clone git://github.com/RichiH/vcsh.git
321     cd vcsh
322     ln -s vcsh /usr/local/bin                       # or add it to your PATH
323     cd
324
325 #### Clone the Template
326
327     vcsh clone git://github.com/RichiH/vcsh_mr_template.git mr
328
329 #### Enable Your Test Repository
330
331     mv ~/.zsh   ~/zsh.bak
332     mv ~/.zshrc ~/zshrc.bak
333     cd $XDG_CONFIG_HOME/mr/config.d/
334     ln -s ../available.d/zsh.vcsh .  # link, and thereby enable, the zsh repository
335     cd
336     mr up
337
338 #### Set Up Your Own Repositories
339
340 Now, it's time to edit the template config and fill it with your own remotes:
341
342     vim $XDG_CONFIG_HOME/mr/available.d/mr.vcsh
343     vim $XDG_CONFIG_HOME/mr/available.d/zsh.vcsh
344
345 And then create your own stuff:
346
347     vcsh init foo
348     vcsh run foo git add -f bar baz quux
349     vcsh run foo git remote add origin git://quuux
350     vcsh run foo git commit
351     vcsh run foo git push
352
353     cp $XDG_CONFIG_HOME/mr/available.d/mr.vcsh $XDG_CONFIG_HOME/mr/available.d/foo.vcsh
354     vim $XDG_CONFIG_HOME/mr/available.d/foo.vcsh # add your own repo
355
356 Done!
357
358 ### The Steal-from-Template Way
359
360 You're welcome to clone the example repository:
361
362     vcsh clone git://github.com/RichiH/vcsh_mr_template.git mr
363     # make sure 'include = cat /usr/share/mr/vcsh' points to an exiting file
364     vim .mrconfig
365
366 Look around in the clone. It should be reasonably simple to understand. If not,
367 poke me, RichiH, on Freenode (query) or OFTC (#vcs-home).
368
369
370 ### The Manual Way
371
372 This is how my old setup procedure looked like. Adapt it to your own style or
373 copy mine verbatim, either is fine.
374
375     # Create workspace
376     mkdir -p ~/work/git
377     cd !$
378
379     # Clone vcsh and make it available
380     git clone git://github.com/RichiH/vcsh.git vcsh
381     sudo ln -s ~/work/git/vcsh/vcsh /usr/bin/local
382     hash -r
383
384 Grab my mr config. see below for details on how I set this up
385
386     vcsh clone ssh://<remote>/mr.git
387     cd $XDG_CONFIG_HOME/mr/config.d/
388     ln -s ../available.d/* .
389
390
391 mr is used to actually retrieve configs, etc
392
393     ~ % cat ~/.mrconfig
394     [DEFAULT]
395     # adapt /usr/share/mr/vcsh to your system if needed
396     include = cat /usr/share/mr/vcsh
397     include = cat $XDG_CONFIG_HOME/mr/config.d/*
398     ~ % echo $XDG_CONFIG_HOME
399     /home/richih/.config
400     ~ % ls $XDG_CONFIG_HOME/mr/available.d # random selection of my repos
401     git-annex gitk.vcsh git.vcsh ikiwiki mr.vcsh reportbug.vcsh snippets.git wget.vcsh zsh.vcsh
402     ~ %
403     # then simply ln -s whatever you want on your local machine from
404     # $XDG_CONFIG_HOME/mr/available.d to $XDG_CONFIG_HOME/mr/config.d
405     ~ % cd
406     ~ % mr -j 5 up
407
408
409 # mr usage ; will be factored out & rewritten
410
411 ### Keeping repositories Up-to-Date
412
413 This is the beauty of it all. Once you are set up, just run:
414
415     mr up
416     mr push
417
418 Neat.
419
420 ### Making Changes
421
422 After you have made some changes, for which you would normally use `git add`
423 and `git commit`, use the vcsh wrapper (like above):
424
425     vcsh run foo git add -f bar baz quux
426     vcsh run foo git commit
427     vcsh run foo git push
428
429 By the way, you'll have to use -f/--force flag with git-add because all files
430 will be ignored by default. This is to show you only useful output when running
431 git-status. A fix for this problem is being worked on.
432
433 ### Using vcsh without mr
434
435 vcsh encourages you to use [mr][mr]. It helps you manage a large number of
436 repositories by running the necessary vcsh commands for you. You may choose not
437 to use mr, in which case you will have to run those commands manually or by
438 other means.
439
440
441 To initialize a new repository: `vcsh init zsh`
442
443 To clone a repository: `vcsh clone ssh://<remote>/zsh.git`
444
445 To interact with a repository, use the regular Git commands, but prepend them
446 with `vcsh run $repository_name`. For example:
447
448     vcsh run zsh git status
449     vcsh run zsh git add -f .zshrc
450     vcsh run zsh git commit
451
452 Obviously, without mr keeping repositories up-to-date, it will have to be done
453 manually. Alternatively, you could try something like this:
454
455     for repo in `vcsh list`; do
456         vcsh run $repo git pull;
457     done
458
459
460 # Contact
461
462 There are several ways to get in touch with the author and a small but committed
463 community around the general idea of version controlling your (digital) life.
464
465 * IRC: #vcs-home on irc.oftc.net
466
467 * Mailing list: [http://lists.madduck.net/listinfo/vcs-home][vcs-home-list]
468
469 * Pull requests or issues on [https://github.com/RichiH/vcsh][vcsh]
470
471
472 [mr]: http://kitenet.net/~joey/code/mr/
473 [talks]: http://richardhartmann.de/talks/
474 [vcsh]: https://github.com/RichiH/vcsh
475 [vcs-home-list]: http://lists.madduck.net/listinfo/vcs-home