INSTALL.md

   1 # Getting started with vcsh #
   2
   3 Below, you will find a few different methods for setting up vcsh:
   4
   5 1. The template way
   6 2. The steal-from-template way
   7 3. The manual way
   8 4. Using vcsh without mr
   9
  10 # 1. The template way #
  11
  12 ## 1.1 Prerequisites ##
  13
  14 Make sure none of the following files/diretories exist for your test (user). If
  15 they do, move them away for now:
  16
  17 * ~/.gitignore
  18 * ~/.mrconfig
  19 * ~/.config/mr/available.d/mr.vcsh
  20 * ~/.config/mr/available.d/zsh.vcsh
  21 * ~/.config/mr/config.d/mr.vcsh
  22 * ~/.config/vcsh/repo.d/mr.git/
  23
  24 All of the files are part of the template repository, the directory is where
  25 the template will be stored.
  26
  27     apt-get install mr               # this is optional, but highly recommended
  28
  29 ## 1.2 Clone the template ##
  30
  31     mkdir -p ~/work/git
  32     cd !$
  33     git clone git://github.com/RichiH/vcsh.git vcsh
  34     cd vcsh
  35     ln -s vcsh /usr/local/bin        # or add it to your PATH
  36     cd
  37     vcsh clone git://github.com/RichiH/vcsh_mr_template.git mr.vcsh
  38
  39 ## 1.3 Enable your test repository ##
  40
  41     mv ~/.zsh   ~/zsh.bak
  42     mv ~/.zshrc ~/zshrc.bak
  43     cd ~/.config/mr/config.d/
  44     ln -s ../available.d/zsh.vcsh .  # link, and thereby enable, the zsh repository
  45     cd
  46     mr up
  47
  48 ## 1.4 Set up your own repositories ##
  49
  50 Now, it's time to edit the template config and fill it with your own remotes:
  51
  52     vim .config/mr/available.d/mr.vcsh
  53     vim .config/mr/available.d/zsh.vcsh
  54
  55 And then create your own stuff:
  56
  57     vcsh init foo
  58     vcsh run foo git add -f bar baz quux
  59     vcsh run foo git remote add origin git://quuux
  60     vcsh run foo git commit
  61     vcsh run foo git push
  62
  63     cp .config/mr/available.d/mr.vcsh .config/mr/available.d/foo.vcsh
  64     vim .config/mr/available.d/foo.vcsh # add your own repo
  65
  66 Done!
  67
  68 ## 1.5 Daily use  ##
  69
  70 ### 1.5.1 Keeping repositories up-to-date ###
  71
  72 This is the beauty of it all. Once you are set up, just run:
  73
  74    mr up
  75    mr push
  76
  77 Neat.
  78
  79 ### 1.5.2 Making changes ###
  80
  81 After you have made some changes, for which you would normally use `git add`
  82 and `git commit`, use the vcsh wrapper (like above):
  83
  84     vcsh run foo git add -f bar baz quux
  85     vcsh run foo git commit
  86     vcsh run foo git push
  87
  88 By the way, you'll have to use -f/--force flag with git-add because all files
  89 will be ignored by default. This is to show you only useful output when running
  90 git-status. A fix for this problem is being worked on.
  91
  92
  93 # 2. The steal-from-template way #
  94
  95 You're welcome to clone the example repository:
  96
  97     git clone git://github.com/RichiH/vcsh_mr_template.git
  98
  99 Look around in the clone. It should be reasonably simple to understand. If not,
 100 poke me, RichiH, on Freenode (query) or OFTC (#vcs-home).
 101
 102
 103 # 3. The manual way #
 104
 105 This is how my old setup procedure looked like. Adapt it to your own style or
 106 copy mine verbatim, either is fine.
 107
 108     # Create workspace
 109     mkdir -p ~/work/git
 110     cd !$
 111
 112     # Clone vcsh and make it available
 113     git clone git://github.com/RichiH/vcsh.git vcsh
 114     sudo ln -s ~/work/git/vcsh/vcsh /usr/bin/local
 115     hash -r
 116
 117 Grab my mr config. see below for details on how I set this up
 118
 119     vcsh clone ssh://<remote>/mr.git
 120     cd ~/.config/mr/config.d/
 121     ln -s ../available.d/* .
 122
 123
 124 mr is used to actually retrieve configs, etc
 125
 126     ~ % cat ~/.mrconfig
 127     [DEFAULT]
 128     include = cat ~/.config/mr/config.d/*
 129     ~ % echo $XDG_CONFIG_HOME
 130     /home/richih/.config
 131     ~ % ls $XDG_CONFIG_HOME/mr/available.d # random selection of my repos
 132     git-annex gitk.vcsh git.vcsh ikiwiki mr.vcsh reportbug.vcsh snippets.git wget.vcsh zsh.vcsh
 133     ~ %
 134     # then simply ln -s whatever you want on your local machine from
 135     # $XDG_CONFIG_HOME/mr/available.d to $XDG_CONFIG_HOME/mr/config.d
 136     ~ % cd
 137     ~ % mr -j 5 up
 138
 139 # 4. Using vcsh without mr #
 140
 141 vcsh encourages you to use mr. It helps you manage a large number of
 142 repositories by running the necessary vcsh commands for you. You may choose not
 143 to use mr, in which case you will have to run those commands manually or by
 144 other means.
 145
 146 ## 4.1 A few examples ##
 147
 148 To initialize a new repository: `vcsh init zsh`
 149
 150 To clone a repository: `vcsh clone ssh://<remote>/zsh.git`
 151
 152 To interact with a repository, use the regular Git commands, but prepend them
 153 with `vcsh run $repository_name`. For example:
 154
 155     vcsh run zsh git status
 156     vcsh run zsh git add -f .zshrc
 157     vcsh run zsh git commit
 158
 159 Obviously, without mr keeping repositories up-to-date, it will have to be done
 160 manually. Alternatively, you could try something like this:
 161
 162     for repo in `vcsh list`; do
 163         vcsh run $repo git pull;
 164     done
 165
 166 ----------
 167 Questions? RichiH@{Freenode,OFTC,IRCnet}