1MR(1) mr MR(1)
2
6 mr - a Multiple Repository management tool
7
9 mr [options] checkout
10 mr [options] update
12 mr [options] status
14 mr [options] commit [-m "message"]
16 mr [options] record [-m "message"]
18 mr [options] diff
20 mr [options] log
22 mr [options] bootstrap url [directory]
24 mr [options] register [repository]
26 mr [options] config section ["parameter=[value]" ...]
28 mr [options] action [params ...]
30 mr [options] [online|offline]
32 mr [options] remember action [params ...]
34
36 mr is a Multiple Repository management tool. It can checkout, update,
37 or perform other actions on a set of repositories as if they were one
38 combined repository. It supports any combination of subversion, git,
39 cvs, mercurial, bzr, darcs and fossil repositories, and support for
40 other revision control systems can easily be added.
41 mr cds into and operates on all registered repositories at or below
43 your working directory. Or, if you are in a subdirectory of a
44 repository that contains no other registered repositories, it will stay
45 in that directory, and work on only that repository,
46 mr is configured by .mrconfig files, which list the repositories. It
48 starts by reading the .mrconfig file in your home directory, and this
49 can in turn chain load .mrconfig files from repositories.
50 These predefined commands should be fairly familiar to users of any
52 revision control system:
53 checkout (or co)
55 Checks out any repositories that are not already checked out.
56 update
58 Updates each repository from its configured remote repository.
59 If a repository isn't checked out yet, it will first check it out.
61 status
63 Displays a status report for each repository, showing what
64 uncommitted changes are present in the repository.
65 commit (or ci)
67 Commits changes to each repository. (By default, changes are pushed
68 to the remote repository too, when using distributed systems like
69 git. If you don't like this default, you can change it in your
70 .mrconfig, or use record instead.)
71 The optional -m parameter allows specifying a commit message.
73 record
75 Records changes to the local repository, but does not push them to
76 the remote repository. Only supported for distributed revision
77 control systems.
78 The optional -m parameter allows specifying a commit message.
80 push
82 Pushes committed local changes to the remote repository. A no-op
83 for centralized revision control systems.
84 diff
86 Show a diff of uncommitted changes.
87 log Show the commit log.
89 These commands are also available:
91 bootstrap url [directory]
93 Causes mr to download the url, and use it as a .mrconfig file to
94 checkout the repositories listed in it, into the specified
95 directory.
96 The directory will be created if it does not exist. If no directory
98 is specified, the current directory will be used.
99 If the .mrconfig file includes a repository named ".", that is
101 checked out into the top of the specified directory.
102 list (or ls)
104 List the repositories that mr will act on.
105 register
107 Register an existing repository in a mrconfig file. By default, the
108 repository in the current directory is registered, or you can
109 specify a directory to register.
110 The mrconfig file that is modified is chosen by either the -c
112 option, or by looking for the closest known one at or below the
113 current directory.
114 config
116 Adds, modifies, removes, or prints a value from a mrconfig file.
117 The next parameter is the name of the section the value is in. To
118 add or modify values, use one or more instances of
119 "parameter=value". Use "parameter=" to remove a parameter. Use just
120 "parameter" to get the value of a parameter.
121 For example, to add (or edit) a repository in src/foo:
123 mr config src/foo checkout="svn co svn://example.com/foo/trunk foo"
125 To show the command that mr uses to update the repository in
127 src/foo:
128 mr config src/foo update
130 To see the built-in library of shell functions contained in mr:
132 mr config DEFAULT lib
134 The ~/.mrconfig file is used by default. To use a different config
136 file, use the -c option.
137 offline
139 Advises mr that it is in offline mode. Any commands that fail in
140 offline mode will be remembered, and retried when mr is told it's
141 online.
142 online
144 Advices mr that it is in online mode again. Commands that failed
145 while in offline mode will be re-run.
146 remember
148 Remember a command, to be run later when mr re-enters online mode.
149 This implicitly puts mr into offline mode. The command can be any
150 regular mr command. This is useful when you know that a command
151 will fail due to being offline, and so don't want to run it right
152 now at all, but just remember to run it when you go back online.
153 help
155 Displays this help.
156 Actions can be abbreviated to any unambiguous substring, so "mr st" is
158 equivalent to "mr status", and "mr up" is equivalent to "mr update"
159 Additional parameters can be passed to most commands, and are passed on
161 unchanged to the underlying revision control system. This is mostly
162 useful if the repositories mr will act on all use the same revision
163 control system.
164
166 -d directory
167 --directory directory
168 Specifies the topmost directory that mr should work in. The default
169 is the current working directory.
170 -c mrconfig
172 --config mrconfig
173 Use the specified mrconfig file. The default is ~/.mrconfig
174 -p
176 --path
177 Search in the current directory, and its parent directories and use
178 the first .mrconfig found, instead of the default ~/.mrconfig.
179 -v
181 --verbose
182 Be verbose.
183 -q
185 --quiet
186 Be quiet.
187 -k
189 --insecure
190 Accept untrusted SSL certificates when bootstrapping.
191 -s
193 --stats
194 Expand the statistics line displayed at the end to include
195 information about exactly which repositories failed and were
196 skipped, if any.
197 -i
199 --interactive
200 Interactive mode. If a repository fails to be processed, a subshell
201 will be started which you can use to resolve or investigate the
202 problem. Exit the subshell to continue the mr run.
203 -n [number]
205 --no-recurse [number]
206 If no number if specified, just operate on the repository for the
207 current directory, do not recurse into deeper repositories.
208 If a number is specified, will recurse into repositories at most
210 that many subdirectories deep. For example, with -n 2 it would
211 recurse into ./src/foo, but not ./src/packages/bar.
212 -j [number]
214 --jobs [number]
215 Run the specified number of jobs in parallel, or an unlimited
216 number of jobs with no number specified. This can greatly speed up
217 operations such as updates. It is not recommended for interactive
218 operations.
219 Note that running more than 10 jobs at a time is likely to run
221 afoul of ssh connection limits. Running between 3 and 5 jobs at a
222 time will yield a good speedup in updates without loading the
223 machine too much.
224 -t
226 --trust-all
227 Trust all mrconfig files even if they are not listed in ~/.mrtrust.
228 Use with caution.
229
231 Here is an example .mrconfig file:
232 [src]
234 checkout = svn co svn://svn.example.com/src/trunk src
235 chain = true
236 [src/linux-2.6]
238 checkout = git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git &&
239 cd linux-2.6 &&
240 git checkout -b mybranch origin/master
241 The .mrconfig file uses a variant of the INI file format. Lines
243 starting with "#" are comments. Values can be continued to the
244 following line by indenting the line with whitespace.
245 The "DEFAULT" section allows setting default values for the sections
247 that come after it.
248 The "ALIAS" section allows adding aliases for actions. Each parameter
250 is an alias, and its value is the action to use.
251 All other sections add repositories. The section header specifies the
253 directory where the repository is located. This is relative to the
254 directory that contains the mrconfig file, but you can also choose to
255 use absolute paths. (Note that you can use environment variables in
256 section names; they will be passed through the shell for expansion. For
257 example, "[$HOSTNAME]", or "[${HOSTNAME}foo]")
258 Within a section, each parameter defines a shell command to run to
260 handle a given action. mr contains default handlers for "update",
261 "status", "commit", and other standard actions. Normally you only need
262 to specify what to do for "checkout".
263 Note that these shell commands are run in a "set -e" shell environment,
265 where any additional parameters you pass are available in "$@". The
266 "checkout" command is run in the parent of the repository directory,
267 since the repository isn't checked out yet. All other commands are run
268 inside the repository, though not necessarily at the top of it.
269 The "MR_REPO" environment variable is set to the path to the top of the
271 repository. (For the "register" action, "MR_REPO" is instead set to the
272 basename of the directory that should be created when checking the
273 repository out.)
274 The "MR_CONFIG" environment variable is set to the .mrconfig file that
276 defines the repo being acted on, or, if the repo is not yet in a config
277 file, the .mrconfig file that should be modified to register the repo.
278 A few parameters have special meanings:
280 skip
282 If the "skip" parameter is set and its command returns true, then
283 mr will skip acting on that repository. The command is passed the
284 action name in $1.
285 Here are two examples. The first skips the repo unless mr is run by
287 joey. The second uses the hours_since function (included in mr's
288 built-in library) to skip updating the repo unless it's been at
289 least 12 hours since the last update.
290 skip = test `whoami` != joey
292 skip = [ "$1" = update ] && ! hours_since "$1" 12
293 order
295 The "order" parameter can be used to override the default ordering
296 of repositories. The default order value is 10. Use smaller values
297 to make repositories be processed earlier, and larger values to
298 make repositories be processed later.
299 Note that if a repository is located in a subdirectory of another
301 repository, ordering it to be processed earlier is not recommended.
302 chain
304 If the "chain" parameter is set and its command returns true, then
305 mr will try to load a .mrconfig file from the root of the
306 repository.
307 include
309 If the "include" parameter is set, its command is ran, and should
310 output additional mrconfig file content. The content is included as
311 if it were part of the including file.
312 Unlike all other parameters, this parameter does not need to be
314 placed within a section.
315 lib The "lib" parameter can specify some shell code that will be run
317 before each command, this can be a useful way to define shell
318 functions for other commands to use.
319 fixups
321 If the "fixups" parameter is set, its command is run whenever a
322 repository is checked out, or updated. This provides an easy way to
323 do things like permissions fixups, or other tweaks to the
324 repository content, whenever the repository is changed.
325 pre_ and post_
327 If a "pre_action" parameter is set, its command is run before mr
328 performs the specified action. Similarly, "post_action" parameters
329 are run after mr successfully performs the specified action. For
330 example, "pre_commit" is run before committing; "post_update" is
331 run after updating.
332 When looking for a command to run for a given action, mr first looks
334 for a parameter with the same name as the action. If that is not found,
335 it looks for a parameter named "rcs_action" (substituting in the name
336 of the revision control system and the action). The name of the
337 revision control system is itself determined by running each defined
338 "rcs_test" action, until one succeeds.
339 Internally, mr has settings for "git_update", "svn_update", etc. To
341 change the action that is performed for a given revision control
342 system, you can override these rcs specific actions. To add a new
343 revision control system, you can just add rcs specific actions for it.
344 The ~/.mrlog file contains commands that mr has remembered to run
346 later, due to being offline. You can delete or edit this file to remove
347 commands, or even to add other commands for 'mr online' to run. If the
348 file is present, mr assumes it is in offline mode.
349
351 Since mrconfig files can contain arbitrary shell commands, they can do
352 anything. This flexibility is good, but it also allows a malicious
353 mrconfig file to delete your whole home directory. Such a file might be
354 contained inside a repository that your main ~/.mrconfig checks out and
355 chains to. To avoid worries about evil commands in a mrconfig file, mr
356 has the ability to read mrconfig files in untrusted mode. Such files
357 are limited to running only known safe commands (like "git clone") in a
358 carefully checked manner.
359 By default, mr trusts all mrconfig files. (This default will change in
361 a future release!) But if you have a ~/.mrtrust file, mr will only
362 trust mrconfig files that are listed within it. (One file per line.)
363 All other files will be treated as untrusted.
364
366 mr can be extended to support things such as unison and git-svn. Some
367 files providing such extensions are available in /usr/share/mr/. See
368 the documentation in the files for details about using them.
369
371 Copyright 2007-2010 Joey Hess <joey@kitenet.net>
372 Licensed under the GNU GPL version 2 or higher.
374 http://kitenet.net/~joey/code/mr/
376perl v5.12.2 2010-11-02 MR(1)