src/list_packs.txt

   1 Usage: list_packs [-C <dir>] [option ...] ( --only <file> | <directory> )
   2
   3   -C <dir>             change current working director to <dir> before anything
   4   --quiet              no error messages but exit code still set
   5   --all                inspect all *.pack instead of just pack-<sha1>.pack
   6   --exclude-keep       exclude any matching packs with associated .keep
   7   --exclude-no-keep    exclude any matching packs without associated .keep
   8   --exclude-bitmap     exclude any matching packs with associated .bitmap
   9   --exclude-no-bitmap  exclude any matching packs without associated .bitmap
  10   --exclude-bndl       exclude any matching packs with associated .bndl
  11   --exclude-no-bndl    exclude any matching packs without associated .bndl
  12   --exclude-idx        exclude any matching packs with associated .idx
  13   --exclude-no-idx     exclude any matching packs without associated .idx
  14   --exclude-ext <ext>  exclude any matching packs with associated .ext
  15   --exclude-no-ext <e> exclude any matching packs without associated .e
  16   --exclude-limit <n>  exclude any matching packs with at least n objects
  17                        if n is < 0 then exclude packs without at least -n objs
  18   --object-limit <n>   sort matches in ascending (descending if n < 0) order of
  19                        obj count and include packs while total obj count <= n
  20   --include-boundary   include the boundary pack that exceeds --object-limit
  21   --max-matches <n>    limit final output to the first n matches (at most)
  22   --count              instead of pack files output a count of them
  23   --count-objects      instead of pack files output a total object count
  24
  25   --only <file>        inspect only packs named in <file> (use - for stdin)
  26   <directory>          inspect only .pack files in here (see the --all option)
  27
  28   If multiple -C options are given they are processed in the order given and
  29     they are always processed before attempting to open <directory> or <file>.
  30
  31   If a <directory> is given then the --only option may NOT be used.
  32
  33   If the --only option is used then neither --all nor <directory> may be used.
  34
  35   If both --count and --count-objects are given, the last one wins.
  36
  37   If both --exclude-xxx and --exclude-no-xxx are given, then the last one wins.
  38
  39   If neither --exclude-xxx nor --exclude-no-xxx is given, then packs both with
  40     AND without an associated .xxx file match.
  41
  42   The --exclude-ext and --exclude-no-ext options require the given <ext> to
  43     contain no whitespace, ':', '/', '\\' or '.' characters and be no more than
  44     ten characters long.
  45
  46   If --object-limit is given, all other options are first applied as normal,
  47     but the matching packs are collected in a list which is then sorted in
  48     ascending order (descending order if object limit is negative) by the
  49     number of objects in the pack.  Then the list is walked in sorted order
  50     and the total object count computed along the way.  The first pack that
  51     has an object count that causes the total object count so far to EXCEED
  52     the absolute value of the object limit is excluded as well as all
  53     following packs.  However, if --include-boundary is given then the pack
  54     that causes the total object count so far to EXCEED the absolute value of
  55     the object limit will be INCLUDED while all following packs are excluded.
  56     Processing then continues as though only the non-excluded packs matched
  57     meaning final output can still be a count of packs, count of total objects
  58     or list of pack file names depending on the options given.
  59
  60   If --max-matches is given, then after ALL other matching has been performed
  61     only the first n matches (when there are more than n total final matches)
  62     participate in generating the final output.
  63
  64   For --only, pack names are relative to the current directory (but see the -C
  65     option) and MUST include the trailing .pack and MUST be one per line but
  66     any characters after and including the first whitespace or colon character
  67     are ignored on each line.  Empty lines and lines with the first char
  68     whitespace or ':' are ignored.
  69
  70   The --only option will properly read a fast-import --export-pack-edges file.
  71
  72   If an error (other than EOF) occurs while reading the --only file, an error
  73     message will be output (unless the --quiet option is used) and the exit
  74     status will be non-zero.
  75
  76   Output is one pack file name (including the .pack suffix) per line unless
  77     the --count or --count-objects option is used in which case it's a single
  78     decimal count of either the number of pack file names that would have been
  79     output (--count) or the total count of all the objects in all the pack
  80     files that would have been included in the output (--count-objects).
  81
  82   Using the --only option allows files not ending in .pack to be inspected in
  83     which case the --exclude-[no-]xxx options may not work as intended (since
  84     when there is no .pack suffix to remove they will just append the test
  85     suffix without first removing anything).
  86
  87   The --exclude-no-idx option not only checks for the existence of an
  88     associated .idx file, it also verifies the length is at least
  89     1072 + 28 * number of objects in the corresponding .pack file.  However,
  90     it does NOT validate the actual .idx file contents in any way (i.e.
  91     no signature check nor matching object count check).
  92
  93   If an otherwise matching .pack file fails the header sanity check test (it
  94     must have a PACK signature, a version of 2 or 3 and a length of at least
  95     32 + number of objects) or, when --exclude-no-idx is used and the
  96     associated .idx file fails the length check, a message is output to stderr
  97     unless the --quiet option is used.  Using --exclude-no-idx does NOT produce
  98     any error message when there is no associated .idx file, the .pack is just
  99     ignored.
 100
 101   If a file being checked is not actually a file (i.e. a directory or other
 102     non-file), an error message will be output unless the --quiet option is
 103     used.  However, operation then continues as though the non-file did not
 104     exist.