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.
7 mr - a Multiple Repository management tool
11 B<mr> [options] checkout
13 B<mr> [options] update
15 B<mr> [options] status
17 B<mr> [options] commit [-m "message"]
23 B<mr> [options] register [repository]
25 B<mr> [options] config section ["parameter=[value]" ...]
27 B<mr> [options] action [params ...]
31 B<mr> is a Multiple Repository management tool. It can checkout, update, or
32 perform other actions on a set of repositories as if they were one combined
33 respository. It supports any combination of subversion, git, cvs, mecurial and
34 bzr repositories, and support for other revision control systems can easily be
37 B<mr> cds into and operates on all registered repositories at or below your
38 working directory. Or, if you are in a subdirectory of a repository that
39 contains no other registered repositories, it will stay in that directory,
40 and work on only that repository,
42 These predefined commands should be fairly familiar to users of any revision
47 =item checkout (or co)
49 Checks out any repositories that are not already checked out.
53 Updates each repository from its configured remote repository.
55 If a repository isn't checked out yet, it will first check it out.
59 Displays a status report for each repository, showing what
60 uncommitted changes are present in the repository.
64 Commits changes to each repository. (By default, changes are pushed to the
65 remote repository too, when using distributed systems like git.)
67 The optional -m parameter allows specifying a commit message.
71 Show a diff of uncommitted changes.
79 These commands are also available:
85 List the repositories that mr will act on.
89 Register an existing repository in a mrconfig file. By default, the
90 repository in the current directory is registered, or you can specify a
91 directory to register.
93 The mrconfig file that is modified is chosen by either the -c option, or by
94 looking for the closest known one at or below the current directory.
98 Adds, modifies, removes, or prints a value from a mrconfig file. The next
99 parameter is the name of the section the value is in. To add or modify
100 values, use one or more instances of "parameter=value". Use "parameter=" to
101 remove a parameter. Use just "parameter" to get the value of a parameter.
103 For example, to add (or edit) a repository in src/foo:
105 mr config src/foo checkout="svn co svn://example.com/foo/trunk foo"
107 To show the command that mr uses to update the repository in src/foo:
109 mr config src/foo update
111 To see the built-in library of shell functions contained in mr:
113 mr config DEFAULT lib
115 The ~/.mrconfig file is used by default. To use a different config file,
124 Actions can be abbreviated to any unambiguous subsctring, so
125 "mr st" is equivilant to "mr status", and "mr up" is equivilant to "mr
128 Additional parameters can be passed to most commands, and are passed on
129 unchanged to the underlying revision control system. This is mostly useful
130 if the repositories mr will act on all use the same revision control
139 Specifies the topmost directory that B<mr> should work in. The default is
140 the current working directory.
144 Use the specified mrconfig file. The default is B<~/.mrconfig>
152 Expand the statistics line displayed at the end to include information
153 about exactly which repositories failed and were skipped, if any.
157 Just operate on the repository for the current directory, do not
158 recurse into deeper repositories.
164 B<mr> is configured by .mrconfig files. It starts by reading the .mrconfig
165 file in your home directory, and this can in turn chain load .mrconfig files
168 Here is an example .mrconfig file:
171 checkout = svn co svn://svn.example.com/src/trunk src
175 checkout = git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git &&
177 git checkout -b mybranch origin/master
179 The .mrconfig file uses a variant of the INI file format. Lines starting with
180 "#" are comments. Values can be continued to the following line by
181 indenting the line with whitespace.
183 The "DEFAULT" section allows setting default values for the sections that
186 The "ALIAS" section allows adding aliases for actions. Each parameter
187 is an alias, and its value is the action to use.
189 All other sections add repositories. The section header specifies the
190 directory where the repository is located. This is relative to the directory
191 that contains the mrconfig file, but you can also choose to use absolute
194 Within a section, each parameter defines a shell command to run to handle a
195 given action. mr contains default handlers for "update", "status",
196 "commit", and other standard actions. Normally you only need to specify what
197 to do for "checkout".
199 Note that these shell commands are run in a "set -e" shell
200 environment, where any additional parameters you pass are available in
201 "$@". The "checkout" command is run in the parent of the repository
202 directory, since the repository isn't checked out yet. All other commands
203 are run inside the repository, though not necessarily at the top of it.
205 The "MR_REPO" environment variable is set to the path to the top of the
206 repository. The "MR_CONFIG" environment variable is set to the .mrconfig file
207 that defines the repo being acted on, or, if the repo is not yet in a config
208 file, the .mrconfig file that should be modified to register the repo.
210 A few parameters have special meanings:
216 If the "skip" parameter is set and its command returns true, then B<mr>
217 will skip acting on that repository. The command is passed the action
220 Here are two examples. The first skips the repo unless
221 mr is run by joey. The second uses the hours_since function
222 (included in mr's built-in library) to skip updating the repo unless it's
223 been at least 12 hours since the last update.
225 skip = test $(whoami) != joey
226 skip = [ "$1" = update ] && [ $(hours_since "$1") -lt 12 ]
230 If the "chain" parameter is set and its command returns true, then B<mr>
231 will try to load a .mrconfig file from the root of the repository. (You
232 should avoid chaining from repositories with untrusted committers.)
236 The "lib" parameter can specify some shell code that will be run before each
237 command, this can be a useful way to define shell functions for other commands
244 Copyright 2007 Joey Hess <joey@kitenet.net>
246 Licensed under the GNU GPL version 2 or higher.
248 http://kitenet.net/~joey/code/mr/
257 use Cwd qw(getcwd abs_path);
260 print STDERR "mr: interrupted\n";
264 $ENV{MR_CONFIG}="$ENV{HOME}/.mrconfig";
265 my $config_overridden=0;
266 my $directory=getcwd();
275 Getopt::Long::Configure("no_permute");
276 my $result=GetOptions(
277 "d|directory=s" => sub { $directory=abs_path($_[1]) },
278 "c|config=s" => sub { $ENV{MR_CONFIG}=$_[1]; $config_overridden=1 },
279 "v|verbose" => \$verbose,
280 "s|stats" => \$stats,
281 "n|no-recurse" => \$no_recurse,
283 if (! $result || @ARGV < 1) {
284 die("Usage: mr [-d directory] action [params ...]\n".
285 "(Use mr help for man page.)\n");
289 # Make sure MR_CONFIG is an absolute path, but don't use abs_path since
290 # the config file might be a symlink to elsewhere, and the directory it's
292 if ($ENV{MR_CONFIG} !~ /^\//) {
293 $ENV{MR_CONFIG}=getcwd()."/".$ENV{MR_CONFIG};
297 loadconfig($ENV{MR_CONFIG});
299 #print Dumper(\%config);
302 use FindBin qw($Bin $Script);
303 $ENV{MR_PATH}=$Bin."/".$Script;
306 # alias expansion and command stemming
307 my $action=shift @ARGV;
308 if (exists $alias{$action}) {
309 $action=$alias{$action};
311 if (! exists $knownactions{$action}) {
312 my @matches = grep { /^\Q$action\E/ }
313 keys %knownactions, keys %alias;
317 elsif (@matches == 0) {
318 die "mr: unknown action \"$action\" (known actions: ".
319 join(", ", sort keys %knownactions).")\n";
322 die "mr: ambiguous action \"$action\" (matches: ".
323 join(", ", @matches).")\n";
327 # commands that do not operate on all repos
328 if ($action eq 'help') {
329 exec($config{''}{DEFAULT}{$action}) || die "exec: $!";
331 elsif ($action eq 'config') {
333 die "mr config: not enough parameters\n";
336 if ($section=~/^\//) {
337 # try to convert to a path relative to the config file
338 my ($dir)=$ENV{MR_CONFIG}=~/^(.*\/)[^\/]+$/;
340 $dir.="/" unless $dir=~/\/$/;
341 if ($section=~/^\Q$dir\E(.*)/) {
347 if (/^([^=]+)=(.*)$/) {
348 $changefields{$1}=$2;
352 foreach my $topdir (sort keys %config) {
353 if (exists $config{$topdir}{$section} &&
354 exists $config{$topdir}{$section}{$_}) {
355 print $config{$topdir}{$section}{$_}."\n";
357 last if $section eq 'DEFAULT';
361 die "mr $action: $section $_ not set\n";
365 modifyconfig($ENV{MR_CONFIG}, $section, %changefields) if %changefields;
368 elsif ($action eq 'register') {
369 if (! $config_overridden) {
370 # Find the closest known mrconfig file to the current
372 $directory.="/" unless $directory=~/\/$/;
373 foreach my $topdir (reverse sort keys %config) {
374 next unless length $topdir;
375 if ($directory=~/^\Q$topdir\E/) {
376 $ENV{MR_CONFIG}=$configfiles{$topdir};
381 my $command="set -e; ".$config{''}{DEFAULT}{lib}."\n".
382 "my_action(){ $config{''}{DEFAULT}{$action}\n }; my_action ".
383 join(" ", map { s/\//\/\//g; s/"/\"/g; '"'.$_.'"' } @ARGV);
384 print STDERR "mr $action: running >>$command<<\n" if $verbose;
385 exec($command) || die "exec: $!";
388 # work out what repos to act on
391 foreach my $topdir (sort keys %config) {
392 foreach my $subdir (sort keys %{$config{$topdir}}) {
393 next if $subdir eq 'DEFAULT';
394 my $dir=($subdir =~/^\//) ? $subdir : $topdir.$subdir;
396 $dir.="/" unless $dir=~/\/$/;
397 $d.="/" unless $d=~/\/$/;
398 next if $no_recurse && $d ne $dir;
399 next if $dir ne $d && $dir !~ /^\Q$d\E/;
400 push @repos, [$dir, $topdir, $subdir];
404 # fallback to find a leaf repo
405 LEAF: foreach my $topdir (reverse sort keys %config) {
406 foreach my $subdir (reverse sort keys %{$config{$topdir}}) {
407 next if $subdir eq 'DEFAULT';
408 my $dir=($subdir =~/^\//) ? $subdir : $topdir.$subdir;
410 $dir.="/" unless $dir=~/\/$/;
411 $d.="/" unless $d=~/\/$/;
412 if ($d=~/^\Q$dir\E/) {
413 push @repos, [$dir, $topdir, $subdir];
421 my (@failed, @ok, @skipped);
422 foreach my $repo (@repos) {
423 action($action, @$repo);
427 my ($action, $dir, $topdir, $subdir) = @_;
429 $ENV{MR_CONFIG}=$configfiles{$topdir};
430 my $lib=exists $config{$topdir}{$subdir}{lib} ?
431 $config{$topdir}{$subdir}{lib}."\n" : "";
433 if ($action eq 'checkout') {
435 print "mr $action: $dir already exists, skipping checkout\n" if $verbose;
440 $dir=~s/^(.*)\/[^\/]+\/?$/$1/;
443 print "mr $action: creating parent directory $dir\n" if $verbose;
444 my $ret=system("mkdir", "-p", $dir);
447 elsif ($action eq 'update') {
449 return action("checkout", $dir, $topdir, $subdir);
455 if (exists $config{$topdir}{$subdir}{skip}) {
456 my $test="set -e;".$lib.
457 "my_action(){ $config{$topdir}{$subdir}{skip}\n }; my_action '$action'";
458 print "mr $action: running skip test >>$test<<\n" if $verbose;
459 my $ret=system($test);
461 if (($? & 127) == 2) {
462 print STDERR "mr $action: interrupted\n";
466 print STDERR "mr $action: skip test received signal ".($? & 127)."\n";
470 if ($ret >> 8 == 0) {
471 print "mr $action: $dir skipped per config file\n" if $verbose;
477 if (! $nochdir && ! chdir($dir)) {
478 print STDERR "mr $action: failed to chdir to $dir: $!\n";
481 elsif (! exists $config{$topdir}{$subdir}{$action}) {
482 print STDERR "mr $action: no defined $action command for $topdir$subdir, skipping\n";
487 print "mr $action: $topdir$subdir\n";
490 print "mr $action: $topdir$subdir (in subdir $directory)\n";
492 my $command="set -e; ".$lib.
493 "my_action(){ $config{$topdir}{$subdir}{$action}\n }; my_action ".
494 join(" ", map { s/\//\/\//g; s/"/\"/g; '"'.$_.'"' } @ARGV);
495 print STDERR "mr $action: running >>$command<<\n" if $verbose;
496 my $ret=system($command);
498 if (($? & 127) == 2) {
499 print STDERR "mr $action: interrupted\n";
503 print STDERR "mr $action: received signal ".($? & 127)."\n";
505 print STDERR "mr $action: failed ($ret)\n" if $verbose;
507 if ($ret >> 8 != 0) {
508 print STDERR "mr $action: command failed\n";
511 print STDERR "mr $action: command died ($ret)\n";
515 if ($action eq 'checkout' && ! -d $dir) {
516 print STDERR "mr $action: $dir missing after checkout\n";;
533 return "$count ".($count > 1 ? $plural : $singular);
537 if (! @ok && ! @failed && ! @skipped) {
538 die "mr $action: no repositories found to work on\n";
540 print "mr $action: finished (".join("; ",
541 showstat($#ok+1, "ok", "ok"),
542 showstat($#failed+1, "failed", "failed"),
543 showstat($#skipped+1, "skipped", "skipped"),
547 print "mr $action: (skipped: ".join(" ", @skipped).")\n";
550 print STDERR "mr $action: (failed: ".join(" ", @failed).")\n";
556 elsif (! @ok && @skipped) {
562 sub loadconfig { #{{{
569 if (ref $f eq 'GLOB') {
578 my $absf=abs_path($f);
579 if ($loaded{$absf}) {
584 ($dir)=$f=~/^(.*\/)[^\/]+$/;
585 if (! defined $dir) {
588 $dir=abs_path($dir)."/";
590 if (! exists $configfiles{$dir}) {
591 $configfiles{$dir}=$f;
594 # copy in defaults from first parent
596 while ($parent=~s/^(.*\/)[^\/]+\/?$/$1/) {
597 if ($parent eq '/') {
600 if (exists $config{$parent} &&
601 exists $config{$parent}{DEFAULT}) {
602 $config{$dir}{DEFAULT}={ %{$config{$parent}{DEFAULT}} };
607 print "mr: loading config $f\n" if $verbose;
608 open($in, "<", $f) || die "mr: open $f: $!\n";
619 next if /^\s*\#/ || /^\s*$/;
620 if (/^\[([^\]]*)\]\s*$/) {
623 elsif (/^(\w+)\s*=\s*(.*)/) {
628 while (@lines && $lines[0]=~/^\s(.+)/) {
635 if (! defined $section) {
636 die "$f line $.: parameter ($parameter) not in section\n";
638 if ($section ne 'ALIAS' &&
639 ! exists $config{$dir}{$section} &&
640 exists $config{$dir}{DEFAULT}) {
642 $config{$dir}{$section}={ %{$config{$dir}{DEFAULT}} };
644 if ($section eq 'ALIAS') {
645 $alias{$parameter}=$value;
647 elsif ($parameter eq 'lib') {
648 $config{$dir}{$section}{lib}.=$value."\n";
651 $config{$dir}{$section}{$parameter}=$value;
652 $knownactions{$parameter}=1;
653 if ($parameter eq 'chain' &&
654 length $dir && $section ne "DEFAULT" &&
655 -e $dir.$section."/.mrconfig") {
656 my $ret=system($value);
658 if (($? & 127) == 2) {
659 print STDERR "mr $action: chain test interrupted\n";
663 print STDERR "mr $action: chain test received signal ".($? & 127)."\n";
667 push @toload, $dir.$section."/.mrconfig";
673 die "$f line $line: parse error\n";
682 sub modifyconfig { #{{{
684 # the section to modify or add
685 my $targetsection=shift;
686 # fields to change in the section
687 # To remove a field, set its value to "".
694 open(my $in, "<", $f) || die "mr: open $f: $!\n";
699 my $formatfield=sub {
701 my @value=split(/\n/, shift);
703 return "$field = ".shift(@value)."\n".
704 join("", map { "\t$_\n" } @value);
708 while ($out[$#out] =~ /^\s*$/) {
709 unshift @blanks, pop @out;
711 foreach my $field (sort keys %changefields) {
712 if (length $changefields{$field}) {
713 push @out, "$field = $changefields{$field}\n";
714 delete $changefields{$field};
724 if (/^\s*\#/ || /^\s*$/) {
727 elsif (/^\[([^\]]*)\]\s*$/) {
728 if (defined $section &&
729 $section eq $targetsection) {
737 elsif (/^(\w+)\s*=\s(.*)/) {
742 while (@lines && $lines[0]=~/^\s(.+)/) {
748 if ($section eq $targetsection) {
749 if (exists $changefields{$parameter}) {
750 if (length $changefields{$parameter}) {
751 $value=$changefields{$parameter};
753 delete $changefields{$parameter};
757 push @out, $formatfield->($parameter, $value);
761 if (defined $section &&
762 $section eq $targetsection) {
765 elsif (%changefields) {
766 push @out, "\n[$targetsection]\n";
767 foreach my $field (sort keys %changefields) {
768 if (length $changefields{$field}) {
769 push @out, $formatfield->($field, $changefields{$field});
774 open(my $out, ">", $f) || die "mr: write $f: $!\n";
779 # Finally, some useful actions that mr knows about by default.
780 # These can be overridden in ~/.mrconfig.
795 for dir in .git .svn .bzr CVS .hg; do
796 if [ -e "$MR_REPO/$dir" ]; then
797 flagfile="$MR_REPO/$dir/.mr_last$1"
801 if [ -z "$flagfile" ]; then
802 error "cannot determine flag filename"
804 perl -wle 'print -f shift() ? int((-M _) * 24) : 9999' "$flagfile"
809 if [ -d "$MR_REPO"/.svn ]; then
811 elif [ -d "$MR_REPO"/.git ]; then
813 git pull -t origin master
817 elif [ -d "$MR_REPO"/.bzr ]; then
819 elif [ -d "$MR_REPO"/CVS ]; then
821 elif [ -d "$MR_REPO"/.hg ]; then
822 hg pull "$@" && hg update "$@"
824 error "unknown repo type"
827 if [ -d "$MR_REPO"/.svn ]; then
829 elif [ -d "$MR_REPO"/.git ]; then
830 git status "$@" || true
831 elif [ -d "$MR_REPO"/.bzr ]; then
833 elif [ -d "$MR_REPO"/CVS ]; then
835 elif [ -d "$MR_REPO"/.hg ]; then
838 error "unknown repo type"
841 if [ -d "$MR_REPO"/.svn ]; then
843 elif [ -d "$MR_REPO"/.git ]; then
844 git commit -a "$@" && git push --all
845 elif [ -d "$MR_REPO"/.bzr ]; then
846 bzr commit "$@" && bzr push
847 elif [ -d "$MR_REPO"/CVS ]; then
849 elif [ -d "$MR_REPO"/.hg ]; then
850 hg commit -m "$@" && hg push
852 error "unknown repo type"
855 if [ -d "$MR_REPO"/.svn ]; then
857 elif [ -d "$MR_REPO"/.git ]; then
859 elif [ -d "$MR_REPO"/.bzr ]; then
861 elif [ -d "$MR_REPO"/CVS ]; then
863 elif [ -d "$MR_REPO"/.hg ]; then
866 error "unknown repo type"
869 if [ -d "$MR_REPO"/.svn ]; then
871 elif [ -d "$MR_REPO"/.git ]; then
873 elif [ -d "$MR_REPO"/.bzr ]; then
875 elif [ -d "$MR_REPO"/CVS ]; then
877 elif [ -d "$MR_REPO"/.hg ]; then
880 error "unknown repo type"
886 basedir="$(basename $(pwd))"
888 url=$(LANG=C svn info . | grep -i ^URL: | cut -d ' ' -f 2)
889 if [ -z "$url" ]; then
890 error "cannot determine svn url"
892 echo "Registering svn url: $url in $MR_CONFIG"
893 mr -c "$MR_CONFIG" config "$(pwd)" checkout="svn co $url $basedir"
894 elif [ -d .git ]; then
895 url=$(LANG=C git-config --get remote.origin.url)
896 if [ -z "$url" ]; then
897 error "cannot determine git url"
899 echo "Registering git url: $url in $MR_CONFIG"
900 mr -c "$MR_CONFIG" config "$(pwd)" checkout="git clone $url $basedir"
901 elif [ -d .bzr ]; then
902 url=$(cat .bzr/branch/parent)
903 if [ -z "$url" ]; then
904 error "cannot determine bzr url"
906 echo "Registering bzr url: $url in $MR_CONFIG"
907 mr -c "$MR_CONFIG" config "$(pwd)" checkout="bzr clone $url $basedir"
908 elif [ -d CVS ]; then
909 repo=$(cat CVS/Repository)
911 if [ -z "$root" ]; then
912 error "cannot determine cvs root"
914 echo "Registering cvs repository $repo at root $root"
915 mr -c "$MR_CONFIG" config "$(pwd)" \
916 checkout="cvs -d '$root' co -d $basedir $repo"
917 elif [ -d .hg ]; then
918 url=$(hg showconfig paths.default)
919 echo "Registering mercurial repo url: $url in $MR_CONFIG"
920 mr -c "$MR_CONFIG" config "$(pwd)" \
921 checkout="hg clone $url $basedir"
923 error "unable to register this repo type"
926 if [ ! -e "$MR_PATH" ]; then
927 error "cannot find program path"
929 (pod2man -c mr "$MR_PATH" | man -l -) || error "pod2man or man failed"
933 ed = echo "A horse is a horse, of course, of course.."
934 T = echo "I pity the fool."
935 right = echo "Not found."