Load extension:

  $ echo "[extensions]" >> $HGRCPATH
  $ echo "onsub = $TESTDIR/onsub.py" >> $HGRCPATH

Check help formatting:

  $ hg help onsub
  hg onsub [-b] [-0] [-t TYPE] [--ignore-errors] CMD [POST-CMD]
  
  execute a command in each subrepository
  
      Executes CMD with the current working directory set to the root of each
      subrepository. By default, execution stops if CMD returns a non-zero exit
      code. Use --ignore-errors to override this.
  
      If a POST-CMD is specified, this will be executed after all
      subrepositories below the current subrepository has been visited. This
      corresponds to a post-order traversal of the tree.
  
      It is an error to specify a POST-CMD together with the --breadth-first
      flag.
  
      Use --verbose/-v to print the command being run and the subrepo name for
      each run of CMD in a subrepo. Alternately, use --print0/-0 to print just
      the subrepo name followed by a NUL character instead of a newline. This
      can be useful in combination with "hg status --print0".
  
      The command has access to the following environment variables:
  
      "HG_REPO":
          Absolute path to the top-level repository in which the onsub command
          was executed.
  
      "HG_SUBPATH":
          Relative path to the current subrepository from the top-level
          repository.
  
      "HG_SUBURL":
          URL for the current subrepository as specified in the containing
          repository's ".hgsub" file.
  
      "HG_SUBSTATE":
          State of the current subrepository as specified in the containing
          repository's ".hgsubstate" file.
  
      "HG_SUBTYPE":
          The type of the current subrepository (hg, git or svn).
  
  options:
  
   -b --breadth-first use breadth-first traversal
   -p --post-order    use post-order depth-first traversal
      --root-repo     include root repository in traversal
      --max-depth N   limit recursion to N levels (negative for no limit)
                      (default: -1)
      --ignore-errors continue execution despite errors
   -t --type TYPE     the type of repo to filter
   -0 --print0        end subrepository names with NUL, for use with xargs
  
  use "hg -v help onsub" to show more info

Create some nicely nested subrepositories:

  $ hg init
  $ for d in a b; do hg init $d; echo "$d = $d" >> .hgsub; done
  $ hg add .hgsub

  $ cd a

  $ for d in x y; do hg init $d; echo "$d = $d" >> .hgsub; done
  $ hg add .hgsub

  $ cd y
  $ for d in r s t; do hg init $d; echo "$d = $d" >> .hgsub; done
  $ hg add .hgsub
  $ cd ..

  $ cd ..

  $ cd b
  $ for d in u v; do hg init $d; echo "$d = $d" >> .hgsub; done
  $ hg add .hgsub
  $ cd ..

  $ hg commit -m init -S
  committing subrepository a
  committing subrepository a/x
  committing subrepository a/y
  committing subrepository a/y/r
  committing subrepository a/y/s
  committing subrepository a/y/t
  committing subrepository b
  committing subrepository b/u
  committing subrepository b/v

The default depth-first pre-order traversal:

  $ hg onsub 'echo $HG_SUBPATH'
  a
  a/x
  a/y
  a/y/r
  a/y/s
  a/y/t
  b
  b/u
  b/v

Traversal including the root repository:

  $ hg onsub 'echo $HG_SUBPATH' --root-repo
  .
  a
  a/x
  a/y
  a/y/r
  a/y/s
  a/y/t
  b
  b/u
  b/v

Depth-first post-order traversal: 

  $ hg onsub 'echo $HG_SUBPATH' --post-order
  a/x
  a/y/r
  a/y/s
  a/y/t
  a/y
  a
  b/u
  b/v
  b

Depth-first pre- and post-order traversal:

  $ hg onsub 'echo pre $HG_SUBPATH'  'echo post $HG_SUBPATH'
  pre a
  pre a/x
  post a/x
  pre a/y
  pre a/y/r
  post a/y/r
  pre a/y/s
  post a/y/s
  pre a/y/t
  post a/y/t
  post a/y
  post a
  pre b
  pre b/u
  post b/u
  pre b/v
  post b/v
  post b

Breadth-first traversal:

  $ hg onsub 'echo $HG_SUBPATH' --breadth-first
  a
  b
  a/x
  a/y
  b/u
  b/v
  a/y/r
  a/y/s
  a/y/t

Limit depth of traversal:
  $ hg onsub --max-depth 1 'echo $HG_SUBPATH'
  a
  b
  $ hg onsub --max-depth 2 'echo $HG_SUBPATH'
  a
  a/x
  a/y
  b
  b/u
  b/v
  $ hg onsub --max-depth 2 -b 'echo $HG_SUBPATH'
  a
  b
  a/x
  a/y
  b/u
  b/v
  $ hg onsub --max-depth 1 -b --root-repo 'echo $HG_SUBPATH'
  .
  a
  b

Test aborting:

  $ hg onsub -v 'test $HG_SUBPATH != "a/y/r"'
  executing 'test $HG_SUBPATH != "a/y/r"' in a
  executing 'test $HG_SUBPATH != "a/y/r"' in a/x
  executing 'test $HG_SUBPATH != "a/y/r"' in a/y
  executing 'test $HG_SUBPATH != "a/y/r"' in a/y/r
  abort: terminated onsub in a/y/r: test exited with status 1
  [255]

Test aborting:

  $ hg onsub -v --ignore-errors false
  executing 'false' in a
  executing 'false' in a/x
  executing 'false' in a/y
  executing 'false' in a/y/r
  executing 'false' in a/y/s
  executing 'false' in a/y/t
  executing 'false' in b
  executing 'false' in b/u
  executing 'false' in b/v

Test --print0:

  $ mv a 'with spaces'
  $ echo 'with spaces = with spaces' > .hgsub
  $ echo 'b = b' >> .hgsub
  $ hg commit -m rename
  committing subrepository with spaces
  $ hg onsub -0 | xargs -n 1 -0
  b
  b/u
  b/v
  with spaces
  with spaces/x
  with spaces/y
  with spaces/y/r
  with spaces/y/s
  with spaces/y/t