1MR(1) mr MR(1)
2
6 mr - a tool to manage all your version control repos
7
9 mr [options] checkout
10 mr [options] update
12 mr [options] status
14 mr [options] clean [-f]
16 mr [options] commit [-m "message"]
18 mr [options] record [-m "message"]
20 mr [options] fetch
22 mr [options] push
24 mr [options] diff
26 mr [options] log
28 mr [options] grep pattern
30 mr [options] run command [param ...]
32 mr [options] bootstrap src [directory]
34 mr [options] register [repository]
36 mr [options] config section ["setting=[value]" ...]
38 mr [options] action [params ...]
40 mr [options] [online|offline]
42 mr [options] remember action [params ...]
44
46 mr is a tool to manage all your version control repos. It can checkout,
47 update, or perform other actions on a set of repositories as if they
48 were one combined repository. It supports any combination of
49 Subversion, git, cvs, mercurial, bzr, darcs, fossil and veracity
50 repositories, and support for other version control systems can easily
51 be added.
52 mr cds into and operates on all registered repositories at or below
54 your working directory. Or, if you are in a subdirectory of a
55 repository that contains no other registered repositories, it will stay
56 in that directory, and work on only that repository,
57 mr is configured by .mrconfig files, which list the repositories. It
59 starts by reading the .mrconfig file in your home directory, and this
60 can in turn chain load .mrconfig files from repositories. It also
61 automatically looks for a .mrconfig file in the current directory, or
62 in one of its parent directories.
63 These predefined commands should be fairly familiar to users of any
65 version control system:
66 checkout (or co)
68 Checks out any repositories that are not already checked out.
69 update
71 Updates each repository from its configured remote repository.
72 If a repository isn't checked out yet, it will first check it out.
74 status
76 Displays a status report for each repository, showing what
77 uncommitted changes are present in the repository. For distributed
78 version control systems, also shows unpushed local branches.
79 clean
81 Print ignored files, untracked files and other cruft in the working
82 directory.
83 The optional -f parameter allows removing the files as well as
85 printing them.
86 commit (or ci)
88 Commits changes to each repository. (By default, changes are pushed
89 to the remote repository too, when using distributed systems like
90 git. If you don't like this default, you can change it in your
91 .mrconfig, or use record instead.)
92 The optional -m parameter allows specifying a commit message.
94 record
96 Records changes to the local repository, but does not push them to
97 the remote repository. Only supported for distributed version
98 control systems.
99 The optional -m parameter allows specifying a commit message.
101 fetch
103 Fetches from each repository's remote repository, but does not
104 update the working copy. Only supported for some distributed
105 version control systems.
106 push
108 Pushes committed local changes to the remote repository. A no-op
109 for centralized version control systems.
110 diff
112 Show a diff of uncommitted changes.
113 log Show the commit log.
115 grep pattern
117 Searches for a pattern in each repository using the grep
118 subcommand. Uses ack or ack-grep on VCS that do not have their own.
119 Ignores the return value from grep subcommands so that you can use
120 "mr -m grep foo" and not get output in non-matching repositories.
121 run command [param ...]
123 Runs the specified command in each repository.
124 These commands are also available:
126 bootstrap src [directory]
128 Causes mr to retrieve the source "src" and use it as a .mrconfig
129 file to checkout the repositories listed in it, into the specified
130 directory.
131 mr understands several types of sources:
133 URL for curl
135 "src" may be an URL understood by curl.
136 copy via ssh
138 To use scp to download, the "src" may have the form
139 "ssh://[user@]host:file".
140 local file
142 You can retrieve the config file by other means and pass its
143 path as "src".
144 standard input
146 If source "src" consists in a single dash "-", config file is
147 read from standard input.
148 The directory will be created if it does not exist. If no directory
150 is specified, the current directory will be used.
151 As a special case, if source "src" includes a repository named ".",
153 that is checked out into the top of the specified directory.
154 list (or ls)
156 List the repositories that mr will act on.
157 register
159 Register an existing repository in a mrconfig file. By default, the
160 repository in the current directory is registered, or you can
161 specify a directory to register.
162 The mrconfig file that is modified is chosen by either the -c
164 option, or by looking for the closest known one at or in a parent
165 of the current directory.
166 config
168 Adds, modifies, removes, or prints a value from a mrconfig file.
169 The next parameter is the name of the section the value is in. To
170 add or modify values, use one or more instances of "setting=value".
171 Use "setting=" to remove a setting. Use just "setting" to get the
172 value of a that setting.
173 For example, to add (or edit) a repository in src/foo:
175 mr config src/foo checkout="svn co svn://example.com/foo/trunk foo"
177 To show the command that mr uses to update the repository in
179 src/foo:
180 mr config src/foo update
182 To see the built-in library of shell functions contained in mr:
184 mr config DEFAULT lib
186 The mrconfig file that is used is chosen by either the -c option,
188 or by looking for the closest known one at or in a parent of the
189 current directory.
190 offline
192 Advises mr that it is in offline mode. Any commands that fail in
193 offline mode will be remembered, and retried when mr is told it's
194 online.
195 online
197 Advices mr that it is in online mode again. Commands that failed
198 while in offline mode will be re-run.
199 remember
201 Remember a command, to be run later when mr re-enters online mode.
202 This implicitly puts mr into offline mode. The command can be any
203 regular mr command. This is useful when you know that a command
204 will fail due to being offline, and so don't want to run it right
205 now at all, but just remember to run it when you go back online.
206 help
208 Displays this help.
209 Actions can be abbreviated to any unambiguous substring, so "mr st" is
211 equivalent to "mr status", and "mr up" is equivalent to "mr update"
212 Additional parameters can be passed to most commands, and are passed on
214 unchanged to the underlying version control system. This is mostly
215 useful if the repositories mr will act on all use the same version
216 control system.
217
219 -d directory
220 --directory directory
221 Specifies the topmost directory that mr should work in. The default
222 is the current working directory.
223 -c mrconfig
225 --config mrconfig
226 Use the specified mrconfig file. The default is to use both
227 ~/.mrconfig as well as look for a .mrconfig file in the current
228 directory, or in one of its parent directories.
229 -f
231 --force
232 Force mr to act on repositories that would normally be skipped due
233 to their configuration.
234 --force-env
236 Force mr to execute even though potentially dangerous environment
237 variables are set.
238 -v
240 --verbose
241 Be verbose.
242 -m
244 --minimal
245 Minimise output. If a command fails or there is any output then the
246 usual output will be shown.
247 -q
249 --quiet
250 Be quiet. This suppresses mr's usual output, as well as any output
251 from commands that are run (including stderr output). If a command
252 fails, the output will be shown.
253 -k
255 --insecure
256 Accept untrusted SSL certificates when bootstrapping.
257 -s
259 --stats
260 Expand the statistics line displayed at the end to include
261 information about exactly which repositories failed and were
262 skipped, if any.
263 -i
265 --interactive
266 Interactive mode. If a repository fails to be processed, a subshell
267 will be started which you can use to resolve or investigate the
268 problem. Exit the subshell to continue the mr run.
269 -n [number]
271 --no-recurse [number]
272 If no number if specified, just operate on the repository for the
273 current directory, do not recurse into deeper repositories.
274 If a number is specified, will recurse into repositories at most
276 that many subdirectories deep. For example, with -n 2 it would
277 recurse into ./src/foo, but not ./src/packages/bar.
278 -j [number]
280 --jobs [number]
281 Run the specified number of jobs in parallel, or an unlimited
282 number of jobs with no number specified. This can greatly speed up
283 operations such as updates. It is not recommended for interactive
284 operations.
285 Note that running more than 10 jobs at a time is likely to run
287 afoul of ssh connection limits. Running between 3 and 5 jobs at a
288 time will yield a good speedup in updates without loading the
289 machine too much.
290 --cache
292 Saves the command output and return values to files in the
293 ~/.mrcache/ directory tree after executing each command.
294 Ignored when being run from subdirs of a repo unless --top is
296 enabled.
297 This is used by the "cache-mr-status.sh" shell extension.
299 --cached
301 For repos where the cache is populated, prints the cached output
302 instead of executing the commands. For repos with an unpopulated
303 cache, executes the commands and stores output into the cache.
304 Ignored when being run from subdirs of a repo unless --top is
306 enabled.
307 This is most useful when the "cache-mr-status.sh" shell extension
309 is enabled.
310 --uncache
312 For repos where the cache is populated, remove the cached output
313 before executing any commands.
314 This may be useful to users of the "cache-mr-status.sh" shell
316 extension.
317 --top
319 When being run from subdirs of a repo, change directory to the top
320 of the repo before running any commands.
321 This is used by the "cache-mr-status.sh" shell extension.
323 -t
325 --trust-all
326 Trust all mrconfig files even if they are not listed in ~/.mrtrust.
327 Use with caution.
328 -p
330 --path
331 This obsolete flag is ignored.
332
334 Here is an example .mrconfig file:
335 [src]
337 checkout = svn checkout svn://svn.example.com/src/trunk src
338 chain = true
339 [src/linux-2.6]
341 checkout = git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git &&
342 cd linux-2.6 &&
343 git checkout -b mybranch origin/master
344 The .mrconfig file uses a variant of the INI file format. Lines
346 starting with "#" are comments. Values can be continued to the
347 following line by indenting the line with whitespace.
348 The "DEFAULT" section allows setting default values for the sections
350 that come after it.
351 The "ALIAS" section allows adding aliases for actions. Each setting is
353 an alias, and its value is the action to use.
354 All other sections add repositories. The section header specifies the
356 directory where the repository is located. This is relative to the
357 directory that contains the mrconfig file, but you can also choose to
358 use absolute paths. (Note that you can use environment variables in
359 section names; they will be passed through the shell for expansion. For
360 example, "[$HOSTNAME]", or "[${HOSTNAME}foo]").
361 Within a section, each setting defines a shell command to run to handle
363 a given action. mr contains default handlers for "update", "status",
364 "commit", and other standard actions.
365 Normally you only need to specify what to do for "checkout". Here you
367 specify the command to run in order to create a checkout of the
368 repository. The command will be run in the parent directory, and must
369 create the repository's directory. So use "git clone", "svn checkout",
370 "bzr branch" or "bzr checkout" (for a bound branch), etc.
371 Note that these shell commands are run in a "set -e" shell environment,
373 where any additional parameters you pass are available in $@. All
374 commands other than "checkout" are run inside the repository, though
375 not necessarily at the top of it.
376 The "MR_REPO" environment variable is set to the path to the top of the
378 repository. (For the "register" action, "MR_REPO" is instead set to the
379 basename of the directory that should be created when checking the
380 repository out.)
381 The "MR_CONFIG" environment variable is set to the .mrconfig file that
383 defines the repo being acted on, or, if the repo is not yet in a config
384 file, the .mrconfig file that should be modified to register the repo.
385 The "MR_ACTION" environment variable is set to the command being run
387 (update, checkout, etc).
388 A few settings have special meanings:
390 skip
392 If "skip" is set and its command returns true, then mr will skip
393 acting on that repository. The command is passed the action name in
394 $1.
395 Here are two examples. The first skips the repo unless mr is run by
397 joey. The second uses the hours_since function (included in mr's
398 built-in library) to skip updating the repo unless it's been at
399 least 12 hours since the last update.
400 [mystuff]
402 checkout = ...
403 skip = test `whoami` != joey
404 [linux]
406 checkout = ...
407 skip = [ "$1" = update ] && ! hours_since "$1" 12
408 Another way to use skip is for a lazy checkout. This makes mr skip
410 operating on a repo unless it already exists. To enable the repo,
411 you have to explicitly check it out (using "mr --force -d foo
412 checkout").
413 [foo]
415 checkout = ...
416 skip = lazy
417 order
419 The "order" setting can be used to override the default ordering of
420 repositories. The default order value is 10. Use smaller values to
421 make repositories be processed earlier, and larger values to make
422 repositories be processed later.
423 Note that if a repository is located in a subdirectory of another
425 repository, ordering it to be processed earlier is not recommended.
426 chain
428 If "chain" is set and its command returns true, then mr will try to
429 load a .mrconfig file from the root of the repository.
430 include
432 If "include" is set, its command is ran, and should output
433 additional mrconfig file content. The content is included as if it
434 were part of the including file.
435 Unlike everything else, "include" does not need to be placed within
437 a section.
438 mr ships several libraries that can be included to add support for
440 additional version control type things (unison, git-svn, git-fake-
441 bare, git-subtree). To include them all, you could use:
442 include = cat /usr/share/mr/*
444 See the individual files for details.
446 deleted
448 If "deleted" is set and its command returns true, then mr will
449 treat the repository as deleted. It won't ever actually delete the
450 repository, but it will warn if it sees the repository's directory.
451 This is useful when one mrconfig file is shared among multiple
452 machines, to keep track of and remember to delete old repositories.
453 lib The "lib" setting can contain some shell code that will be run
455 before each command, this can be a useful way to define shell
456 functions for other commands to use.
457 Unlike most other settings, this can be specified multiple times,
459 in which case the chunks of shell code are accumulatively
460 concatenated together.
461 fixups
463 If "fixups" is set, its command is run whenever a repository is
464 checked out, or updated. This provides an easy way to do things
465 like permissions fixups, or other tweaks to the repository content,
466 whenever the repository is changed.
467 jobs
469 If "jobs" is set, run the specified number of jobs in parallel.
470 This can greatly speed up operations such as updates.
471 Note that running more than 10 jobs at a time is likely to run
473 afoul of ssh connection limits. Running between 3 and 5 jobs at a
474 time will yield a good speedup in updates without loading the
475 machine too much.
476 VCS_action
478 When looking for a command to run for a given action, mr first
479 looks for a setting with the same name as the action. If that is
480 not found, it looks for a setting named "VCS_action" (substituting
481 in the name of the version control system and the action). If that
482 is not found, it looks for a setting named "action_default"
483 (substituting in the name of the action).
484 Internally, mr has settings for "git_update", "svn_update", etc. To
486 change the action that is performed for a given version control
487 system, you can override these VCS specific actions. To add a new
488 version control system, you can just add VCS specific actions for
489 it.
490 pre_ and post_
492 If "pre_action" is set, its command is run before mr performs the
493 specified action. Similarly, "post_action" commands are run after
494 mr successfully performs the specified action. For example,
495 "pre_commit" is run before committing; "post_update" is run after
496 updating.
497 _prepend
499 Any setting can be suffixed with "_prepend", to prepend an
500 additional value to the existing value of the setting. A line
501 ending is added between the additional value and the existing
502 value. In this way, actions can be constructed accumulatively.
503 This is useful for applying modifier commands such as nice, ionice
505 or nocache. To apply modifier commands, ensure you end this suffix
506 with a shell line continuation character (the backslash "\" in most
507 shells) so that the line ending added by this suffix is ignored.
508 _append
510 Any setting can be suffixed with "_append", to append an additional
511 value to the existing value of the setting. Line endings are added
512 at the end of the existing value and after the additional value. In
513 this way, actions can be constructed accumulatively.
514 _default
516 Any setting can be suffixed with "_default", to set the value for
517 the setting when a VCS-specific setting cannot be found. This is
518 mostly for making actions do nothing for most VCS actions by
519 setting action_default to "true" and then setting the action for
520 each VCS that has the action.
521 This is used by the mr "upgrade" extension.
523 VCS_test
525 The name of the version control system is itself determined by
526 running each defined "VCS_test" action, until one succeeds.
527
529 Since mrconfig files can contain arbitrary shell commands, they can do
530 anything. This flexibility is good, but it also allows a malicious
531 mrconfig file to delete your whole home directory. Such a file might be
532 contained inside a repository that your main ~/.mrconfig checks out. To
533 avoid worries about evil commands in a mrconfig file, mr defaults to
534 reading all mrconfig files other than the main ~/.mrconfig in untrusted
535 mode. In untrusted mode, mrconfig files are limited to running only
536 known safe commands (like "git clone") in a carefully checked manner.
537 To configure mr to trust other mrconfig files, list them in ~/.mrtrust.
539 One mrconfig file should be listed per line. Either the full pathname
540 should be listed, or the pathname can start with ~/ to specify a file
541 relative to your home directory.
542
544 The ~/.mrlog file contains commands that mr has remembered to run
545 later, due to being offline. You can delete or edit this file to remove
546 commands, or even to add other commands for 'mr online' to run. If the
547 file is present, mr assumes it is in offline mode.
548
550 mr can be extended to support things such as unison and git-svn. Some
551 files providing such extensions are available in /usr/share/mr/. Some
552 files providing mr shell extensions are in /usr/share/mr.sh/. See the
553 documentation in the files for details about using them.
554
556 mr returns nonzero if a command failed in any of the repositories.
557
559 Copyright 2007-2011 Joey Hess <joey@kitenet.net>
560 Licensed under the GNU GPL version 2 or higher.
562 <https://myrepos.branchable.com/>
564perl v5.38.0 2023-07-20 MR(1)