1MR(1)                                 mr                                 MR(1)
2
3
4

NAME

6       mr - a tool to manage all your version control repos
7

SYNOPSIS

9       mr [options] checkout
10
11       mr [options] update
12
13       mr [options] status
14
15       mr [options] clean [-f]
16
17       mr [options] commit [-m "message"]
18
19       mr [options] record [-m "message"]
20
21       mr [options] fetch
22
23       mr [options] push
24
25       mr [options] diff
26
27       mr [options] log
28
29       mr [options] grep pattern
30
31       mr [options] run command [param ...]
32
33       mr [options] bootstrap src [directory]
34
35       mr [options] register [repository]
36
37       mr [options] config section ["setting=[value]" ...]
38
39       mr [options] action [params ...]
40
41       mr [options] [online|offline]
42
43       mr [options] remember action [params ...]
44

DESCRIPTION

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
53       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
58       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
64       These predefined commands should be fairly familiar to users of any
65       version control system:
66
67       checkout (or co)
68           Checks out any repositories that are not already checked out.
69
70       update
71           Updates each repository from its configured remote repository.
72
73           If a repository isn't checked out yet, it will first check it out.
74
75       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
80       clean
81           Print ignored files, untracked files and other cruft in the working
82           directory.
83
84           The optional -f parameter allows removing the files as well as
85           printing them.
86
87       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
93           The optional -m parameter allows specifying a commit message.
94
95       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
100           The optional -m parameter allows specifying a commit message.
101
102       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
107       push
108           Pushes committed local changes to the remote repository. A no-op
109           for centralized version control systems.
110
111       diff
112           Show a diff of uncommitted changes.
113
114       log Show the commit log.
115
116       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
122       run command [param ...]
123           Runs the specified command in each repository.
124
125       These commands are also available:
126
127       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
132           mr understands several types of sources:
133
134           URL for curl
135               "src" may be an URL understood by curl.
136
137           copy via ssh
138               To use scp to download, the "src" may have the form
139               "ssh://[user@]host:file".
140
141           local file
142               You can retrieve the config file by other means and pass its
143               path as "src".
144
145           standard input
146               If source "src" consists in a single dash "-", config file is
147               read from standard input.
148
149           The directory will be created if it does not exist. If no directory
150           is specified, the current directory will be used.
151
152           As a special case, if source "src" includes a repository named ".",
153           that is checked out into the top of the specified directory.
154
155       list (or ls)
156           List the repositories that mr will act on.
157
158       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
163           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
167       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
174           For example, to add (or edit) a repository in src/foo:
175
176             mr config src/foo checkout="svn co svn://example.com/foo/trunk foo"
177
178           To show the command that mr uses to update the repository in
179           src/foo:
180
181             mr config src/foo update
182
183           To see the built-in library of shell functions contained in mr:
184
185             mr config DEFAULT lib
186
187           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
191       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
196       online
197           Advices mr that it is in online mode again. Commands that failed
198           while in offline mode will be re-run.
199
200       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
207       help
208           Displays this help.
209
210       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
213       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

OPTIONS

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
224       -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
230       -f
231       --force
232           Force mr to act on repositories that would normally be skipped due
233           to their configuration.
234
235       --force-env
236           Force mr to execute even though potentially dangerous environment
237           variables are set.
238
239       -v
240       --verbose
241           Be verbose.
242
243       -m
244       --minimal
245           Minimise output. If a command fails or there is any output then the
246           usual output will be shown.
247
248       -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
254       -k
255       --insecure
256           Accept untrusted SSL certificates when bootstrapping.
257
258       -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
264       -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
270       -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
275           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
279       -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
286           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
291       --cache
292           Saves the command output and return values to files in the
293           ~/.mrcache/ directory tree after executing each command.
294
295           Ignored when being run from subdirs of a repo unless --top is
296           enabled.
297
298           This is used by the "cache-mr-status.sh" shell extension.
299
300       --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
305           Ignored when being run from subdirs of a repo unless --top is
306           enabled.
307
308           This is most useful when the "cache-mr-status.sh" shell extension
309           is enabled.
310
311       --uncache
312           For repos where the cache is populated, remove the cached output
313           before executing any commands.
314
315           This may be useful to users of the "cache-mr-status.sh" shell
316           extension.
317
318       --top
319           When being run from subdirs of a repo, change directory to the top
320           of the repo before running any commands.
321
322           This is used by the "cache-mr-status.sh" shell extension.
323
324       -t
325       --trust-all
326           Trust all mrconfig files even if they are not listed in ~/.mrtrust.
327           Use with caution.
328
329       -p
330       --path
331           This obsolete flag is ignored.
332

MRCONFIG FILES

334       Here is an example .mrconfig file:
335
336         [src]
337         checkout = svn checkout svn://svn.example.com/src/trunk src
338         chain = true
339
340         [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
345       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
349       The "DEFAULT" section allows setting default values for the sections
350       that come after it.
351
352       The "ALIAS" section allows adding aliases for actions. Each setting is
353       an alias, and its value is the action to use.
354
355       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
362       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
366       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
372       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
377       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
382       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
386       The "MR_ACTION" environment variable is set to the command being run
387       (update, checkout, etc).
388
389       A few settings have special meanings:
390
391       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
396           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
401             [mystuff]
402             checkout = ...
403             skip = test `whoami` != joey
404
405             [linux]
406             checkout = ...
407             skip = [ "$1" = update ] && ! hours_since "$1" 12
408
409           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
414             [foo]
415             checkout = ...
416             skip = lazy
417
418       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
424           Note that if a repository is located in a subdirectory of another
425           repository, ordering it to be processed earlier is not recommended.
426
427       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
431       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
436           Unlike everything else, "include" does not need to be placed within
437           a section.
438
439           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
443             include = cat /usr/share/mr/*
444
445           See the individual files for details.
446
447       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
454       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
458           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
462       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
468       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
472           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
477       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
485           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
491       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
498       _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
504           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
509       _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
515       _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
522           This is used by the mr "upgrade" extension.
523
524       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

UNTRUSTED MRCONFIG FILES

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
538       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

OFFLINE LOG FILE

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

EXTENSIONS

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

EXIT STATUS

556       mr returns nonzero if a command failed in any of the repositories.
557

AUTHOR

559       Copyright 2007-2011 Joey Hess <joey@kitenet.net>
560
561       Licensed under the GNU GPL version 2 or higher.
562
563       <https://myrepos.branchable.com/>
564
565
566
567perl v5.36.0                      2023-01-19                             MR(1)
Impressum