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