]> 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:

Create .gitignore
[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
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}