]> git.madduck.net Git - code/vcsh.git/blob - INSTALL.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:

Merge branch 'master' of github.com:RichiH/vcsh
[code/vcsh.git] / 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 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 ## 1.2 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 ## 1.3 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 ## 1.4 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 ## 1.5 Daily use  ##
67
68 ### 1.5.1 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 ### 1.5.2 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 ## 4.1 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}