]> git.madduck.net Git - code/vcsh.git/blobdiff - INSTALL

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:

Merge branch 'master' of github.com:RichiH/vcsh
[code/vcsh.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index 5ac7510f7c84980228f0ede52fce0fca3abaf95f..13f7b328825cfeed4fcc4729d8dca124fa744ca7 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -1,60 +1,70 @@
-=The template way=
+# Getting started with vcsh #
 
-==Prerequisites==
+Below you will find three methods for setting up vcsh:
 
-Make sure none of those files/diretories exist for your test (user). If they do, move them away for now:
+1. The template way
+2. The steal-from-template way
+3. The manual way
 
-~/.gitignore
-~/.mrconfig
-~/.config/mr/available.d/mr.vcsh
-~/.config/mr/available.d/zsh.vcsh
-~/.config/mr/config.d/mr.vcsh
-~/.config/vcsh/repo.d/mr.git/
+# 1. The template way #
 
-All of the files are part of the template repo, the directory is where the template will be stored
+## Prerequisites ##
 
-apt-get install mr # this is optional, but highly recommended
+Make sure none of the following files/diretories exist for your test (user). If they do, move them away for now:
 
-==Clone the template==
+* ~/.gitignore
+* ~/.mrconfig
+* ~/.config/mr/available.d/mr.vcsh
+* ~/.config/mr/available.d/zsh.vcsh
+* ~/.config/mr/config.d/mr.vcsh
+* ~/.config/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               # this is optional, but highly recommended
+
+## Clone the template ##
 
     mkdir -p ~/work/git
     cd !$
     git clone git://github.com/RichiH/vcsh.git vcsh
     cd vcsh
-    ln -s vcsh /usr/local/bin
+    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.vcsh
 
-==Enable your test repository==
+## Enable your test repository ##
 
     mv ~/.zsh   ~/zsh.bak
-    mv ~/.zshrc ~/zsh.bak
+    mv ~/.zshrc ~/zshrc.bak
     cd ~/.config/mr/config.d/
-    ln -s ../available.d/mr.vcsh .
+    ln -s ../available.d/zsh.vcsh .  # link, and thereby enable, the zsh repository
     cd
     mr up
 
-==Set up your own repos==
+## Set up your own repositories ##
 
 Now, it's time to edit the template config and fill it with your own remotes:
 
     vim .config/mr/available.d/mr.vcsh
     vim .config/mr/available.d/zsh.vcsh
 
-And then create your own stuff
+And then create your own stuff:
 
     vcsh init foo
     vcsh run foo git add -f bar baz quux
     vcsh run foo git remote add origin git://quuux
     vcsh run foo git commit
     vcsh run foo git push
-    
+
     cp .config/mr/available.d/mr.vcsh .config/mr/available.d/foo.vcsh
     vim .config/mr/available.d/foo.vcsh # add your own repo
 
 Done!
 
-==Daily use==
+## Daily use  ##
+
+### Keeping repositories up-to-date ###
 
 This is the beauty of it all. Once you are set up, just run:
 
@@ -63,38 +73,48 @@ This is the beauty of it all. Once you are set up, just run:
 
 Neat.
 
+### Making changes ###
 
-=The steal-from-template way=
+After you have made some changes, for which you would normally use `git add` and `git commit`, use the vcsh wrapper (like above):
+
+    vcsh run foo git add -f bar baz quux
+    vcsh run foo git commit
+    vcsh run foo git push
+
+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.
+
+
+# 2. The steal-from-template way #
+
+You're welcome to clone the example repository:
 
     git clone git://github.com/RichiH/vcsh_mr_template.git
 
-Then look around in the clone. Should be reasonable simple to understand. If not, poke me RichiH on freenode (query) or OFTC (#vcs-home).
+Look around in the clone. It should be reasonably simple to understand. If not, poke me, RichiH, on Freenode (query) or OFTC (#vcs-home).
 
 
-=The manual way=
+# 3. The manual way #
 
-# This is how my setup looks. Adapt to your style or copy mine verbatim, both is fine.
+This is how my old setup procedure looked like. Adapt it to your own style or copy mine verbatim, either is fine.
 
-# Create workspace
+    # Create workspace
     mkdir -p ~/work/git
     cd !$
 
-# Clone vcsh and make it available
+    # Clone vcsh and make it available
     git clone git://github.com/RichiH/vcsh.git vcsh
     sudo ln -s ~/work/git/vcsh/vcsh /usr/bin/local
     hash -r
 
-# Grab my mr config. see below for details on how I set this up
+Grab my mr config. see below for details on how I set this up
+
     vcsh clone ssh://<remote>/mr.git
     cd ~/.config/mr/config.d/
     ln -s ../available.d/* .
 
 
-
-
-################
-
-# mr is used to actually retrieve configs, etc
+mr is used to actually retrieve configs, etc
 
     ~ % cat ~/.mrconfig
     [DEFAULT]
@@ -103,8 +123,8 @@ Then look around in the clone. Should be reasonable simple to understand. If not
     /home/richih/.config
     ~ % ls $XDG_CONFIG_HOME/mr/available.d # random selection of my repos
     git-annex gitk.vcsh git.vcsh ikiwiki mr.vcsh reportbug.vcsh snippets.git wget.vcsh zsh.vcsh
-    ~ % 
-# then simply ln -s whatever you want on your local machine from
-# $XDG_CONFIG_HOME/mr/available.d to $XDG_CONFIG_HOME/mr/config.d
+    ~ %
+    # then simply ln -s whatever you want on your local machine from
+    # $XDG_CONFIG_HOME/mr/available.d to $XDG_CONFIG_HOME/mr/config.d
     ~ % cd
     ~ % mr -j 5 up