{ "content": [ { "type": "text", "text": "# debbisect(1) (man)\n\n**Summary:** debbisect - bisect snapshot.debian.org\n\n## Flags\n\n| Flag | Long | Arg | Description |\n|------|------|-----|-------------|\n| -h | --help | — | show this help message and exit |\n| -d | --debug | — | Print lots of debugging statements |\n| -v | --verbose | — | Be verbose --cache CACHE cache directory -- by default $TMPDIR is used |\n| — | --nocache | — | disable cache --port PORT manually choose port number for the apt cache instead of automatically choosing a free port -- |\n| — | --no-find-exact-package | — | Normally, when the --depends argument is given so that debbisect takes care of manag‐ ing dependencies, the precise pack |\n\n## Examples\n\n- `Just run \"dosomething\" which runs the test and returns a non-zero exit on failure.`\n- `$ ./debbisect \"last week\" today \"mmdebstrap --customize-hook='chroot \\\"\\$1\\\" dosome‐`\n- `thing' unstable - \\$DEBIANBISECTMIRROR >/dev/null\"`\n- `$ diff -u debbisect.log.good debbisect.log.bad`\n- `Since the command can easily become very long and quoting very involved, lets instead use a`\n- `script:`\n- `$ cat << END > script.sh`\n- `> #!/bin/sh`\n- `> set -exu`\n- `> mmdebstrap \\`\n- `> --verbose \\`\n- `> --aptopt='Acquire::Check-Valid-Until \"false\"' \\`\n- `> --variant=apt \\`\n- `> --include=pkga,pkgb,pkgc \\`\n- `> --customize-hook='chroot \"$1\" dpkg -l' \\`\n- `> --customize-hook='chroot \"$1\" dosomething' \\`\n- `> unstable \\`\n- `> - \\`\n- `> $DEBIANBISECTMIRROR \\`\n- `> >/dev/null`\n- `> END`\n- `$ chmod +x script.sh`\n- `$ ./debbisect --verbose --cache=./cache \"two years ago\" yesterday ./script.sh`\n- `$ diff -u debbisect.log.good debbisect.log.bad`\n- `$ rm -r ./cache`\n- `This example sets Acquire::Check-Valid-Until to not fail on snapshot timestamps from \"two`\n- `years ago\", uses the \"apt\" variant (only Essential:yes plus apt), installs the packages re‐`\n- `quired for the test using --include, runs \"dpkg -l\" so that we can see which packages dif‐`\n- `fered in the logs at the end and uses --cache=cache so that the apt cache does not get dis‐`\n- `carded at the end and the command can be re-run without downloading everything from snap‐`\n- `shot.debian.org again.`\n- `If you want to build a source package you can use the script shipped by devscripts as`\n- `/usr/share/doc/devscripts/examples/debbisectbuildsrc.sh and either use it unmodified like`\n- `this:`\n- `$ DEBIANBISECTSRCPKG=mysrc ./debbisect \"two years ago\" yesterday >`\n- `/usr/share/doc/devscripts/examples/debbisectbuildsrc.sh`\n- `or use the script as a starting point to do your own custom builds.`\n- `Once debbisect has finished bisecting and figured out the last good and the first bad time‐`\n- `stamp, there might be more than one package that differs in version between these two time‐`\n- `stamps. debbisect can figure out which package is the culprit if you hand it control over in‐`\n- `stalling dependencies for you via the --depends option. With that option active, the script`\n- `will not be responsible to set up a chroot itself but is given the path to an existing chroot`\n- `as the first argument. Here is a real example that verifies the package responsible for De‐`\n- `bian bug #912935:`\n- `$ ./debbisect --depends=botch \"2018-11-17\" \"2018-11-22\" 'chroot \"$1\" botch-dose2html`\n- `--packages=/dev/null --help'`\n- `[...] test upgrading python3-minimal 3.6.7-1 -> 3.7.1-2...`\n- `upgrading python3-minimal triggered the problem`\n- `If you want to run above test under qemu, then you would run:`\n- `$ ./debbisect --depends=botch --qemu=defaults \"2018-11-17\" \"2018-11-22\" 'ssh -F \"$1\"`\n- `qemu botch-dose2html --packages=/dev/null --help'`\n- `In the last two examples we omitted the --cache argument for brevity. But please make use of`\n- `it to reduce the load on snapshot.debian.org.`\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **DESCRIPTION** (29 lines) — 7 subsections\n - positional arguments: (9 lines)\n - options: (1 lines)\n - -h --help (2 lines)\n - -d --debug (2 lines)\n - -v --verbose (5 lines)\n - --nocache (28 lines)\n - --no-find-exact-package (5 lines)\n- **TIMESTAMPS** (18 lines)\n- **ENVIRONMENT VARIABLES** (18 lines)\n- **EXAMPLES** (70 lines)\n- **AUTHOR** (5 lines)\n\n## Full Content\n\n### NAME\n\ndebbisect - bisect snapshot.debian.org\n\n### DESCRIPTION\n\nusage: debbisect [-h] [-d] [-v] [--cache CACHE] [--nocache] [--port PORT]\n\n[--depends DEPENDS] [--qemu QEMU] [--architecture ARCHITECTURE] [--suite SUITE]\n[--components COMPONENTS] [--no-find-exact-package] good bad script\n\nExecute a script or a shell snippet for a known good timestamp and a known bad timestamp and\nthen bisect the timestamps until a timestamp from snapshot.debian.org is found where the\nscript first fails. Environment variables are used to tell the script which timestamp to\ntest. See ENVIRONMENT VARIABLES below. At the end of the execution, the files debbi‐\nsect.log.good and debbisect.log.bad are the log files of the last good and last bad run, re‐\nspectively. By default, a temporary caching mirror is executed to reduce bandwidth usage on\nsnapshot.debian.org. If you plan to run debbisect multiple times on a similar range of time‐\nstamps, consider setting a non-temporary cache directory with the --cache option.\n\nThe program has three basic modes of operation. In the first, the given script is responsible\nto set up everything as needed:\n\n$ ./debbisect \"last week\" today script.sh\n$ diff -u debbisect.log.good debbisect.log.bad\n\nIf also the --depends option is given, then a chroot of the correct timestamp will be created\neach time and the script will receive as first argument the path to that chroot. Addition‐\nally, this mode allows debbisect to figure out the exact package that was responsible for the\nfailure instead of only presenting you the last good and first bad timestamp.\n\nLastly, you can also provide the --qemu option. In this mode, your test will be create a qemu\nvirtual machine of the correct timestamp each time. The script will receive the correct ssh\nconfig to log into a host named qemu and execute arbitrary commands.\n\n#### positional arguments:\n\ngood good timestamp -- see section TIMESTAMPS for valid formats\n\nbad bad timestamp -- see section TIMESTAMPS for valid formats\n\nscript test script -- can either be a shell code snippet or an executable script. A non zero\nexit code indicates failure. When also --depends is used, then the first argument to\nthe script will be the chroot directory. When --qemu is used, then the first argument\nto the script will an ssh config for a host named qemu.\n\n#### options:\n\n#### -h --help\n\nshow this help message and exit\n\n#### -d --debug\n\nPrint lots of debugging statements\n\n#### -v --verbose\n\nBe verbose\n\n--cache CACHE\ncache directory -- by default $TMPDIR is used\n\n#### --nocache\n\ndisable cache\n\n--port PORT\nmanually choose port number for the apt cache instead of automatically choosing a free\nport\n\n--depends DEPENDS\nComma separated list of binary packages the test script requires. With this option,\nthe test script will run inside a chroot with the requested packages installed.\n\n--qemu QEMU\nCreate qemu virtual machine and pass a ssh config file to the test script. This argu‐\nment takes a commaseparated series of key=value pairs to specify the virtual machine\nmemory size (via memsize) and the virtual machine disksize (via disksize). Sizes are\nmeasured in bytes or with common unit suffixes like M or G. To pick the default values\n(disksize=4G,memsize=1G) the shorthand 'defaults' can be passed.\n\n--architecture ARCHITECTURE\nChosen architecture when creating the chroot with --depends or --qemu (default: native\narchitecture)\n\n--suite SUITE\nChosen suite when creating the chroot with --depends or --qemu (default: unstable)\n\n--components COMPONENTS\nChosen components (separated by comma or whitespace) when creating the chroot with\n--depends or --qemu (default: main)\n\n#### --no-find-exact-package\n\nNormally, when the --depends argument is given so that debbisect takes care of manag‐\ning dependencies, the precise package that introduced the problem is determined after\nbisection by installing the packages that differ between the last good and first bad\ntimestamp one by one. This option disables this feature.\n\n### TIMESTAMPS\n\nValid good and bad timestamp formats are either:\n\n> the format used by snapshot.debian.org\n> ISO 8601 (with or without time, seconds and timezone)\n> RFC 2822 (used in debian/changelog)\n> all formats understood by the Python dateutil module (if installed)\n> all formats understood by the Python parsedatetime module (if installed)\n\nWithout specifying the timezone explicitly, the local offset is used.\n\nExamples (corresponding to the items in above list, respectively):\n\n> 20200313T065326Z\n> 2020-03-13T06:53:26+00:00\n> Fri, 29 Nov 2019 14:00:08 +0100\n> 5:50 A.M. on June 13, 1990\n> two weeks ago\n\n### ENVIRONMENT VARIABLES\n\nThe following environment variables are available to the test script:\n\nDEBIANBISECTMIRROR Contains the caching mirror address.\n\nDEBIANBISECTEPOCH Contains an integer representing the unix epoch of the\n\ncurrent timestamp. The value of this variable can\ndirectly be assigned to SOURCEDATEEPOCH.\n\nDEBIANBISECTTIMESTAMP Contains a timestamp in the format used by\n\nsnapshot.debian.org. Can also be generated from\nDEBIANBISECTEPOCH via: date --utc --date=@$DEBIANBISECTEPOCH +%Y%m%dT%H%M%SZ\n\nDEBIANBISECT* All environment variables starting with DEBIANBISECT\n\nare passed to the test script.\n\n### EXAMPLES\n\nJust run \"dosomething\" which runs the test and returns a non-zero exit on failure.\n\n$ ./debbisect \"last week\" today \"mmdebstrap --customize-hook='chroot \\\"\\$1\\\" dosome‐\nthing' unstable - \\$DEBIANBISECTMIRROR >/dev/null\"\n$ diff -u debbisect.log.good debbisect.log.bad\n\nSince the command can easily become very long and quoting very involved, lets instead use a\nscript:\n\n$ cat << END > script.sh\n\n> #!/bin/sh\n> set -exu\n> mmdebstrap \\\n> --verbose \\\n> --aptopt='Acquire::Check-Valid-Until \"false\"' \\\n> --variant=apt \\\n> --include=pkga,pkgb,pkgc \\\n> --customize-hook='chroot \"$1\" dpkg -l' \\\n> --customize-hook='chroot \"$1\" dosomething' \\\n> unstable \\\n> - \\\n> $DEBIANBISECTMIRROR \\\n> >/dev/null\n> END\n\n$ chmod +x script.sh\n$ ./debbisect --verbose --cache=./cache \"two years ago\" yesterday ./script.sh\n$ diff -u debbisect.log.good debbisect.log.bad\n$ rm -r ./cache\n\nThis example sets Acquire::Check-Valid-Until to not fail on snapshot timestamps from \"two\nyears ago\", uses the \"apt\" variant (only Essential:yes plus apt), installs the packages re‐\nquired for the test using --include, runs \"dpkg -l\" so that we can see which packages dif‐\nfered in the logs at the end and uses --cache=cache so that the apt cache does not get dis‐\ncarded at the end and the command can be re-run without downloading everything from snap‐\nshot.debian.org again.\n\nIf you want to build a source package you can use the script shipped by devscripts as\n/usr/share/doc/devscripts/examples/debbisectbuildsrc.sh and either use it unmodified like\nthis:\n\n$ DEBIANBISECTSRCPKG=mysrc ./debbisect \"two years ago\" yesterday >\n/usr/share/doc/devscripts/examples/debbisectbuildsrc.sh\n\nor use the script as a starting point to do your own custom builds.\n\nOnce debbisect has finished bisecting and figured out the last good and the first bad time‐\nstamp, there might be more than one package that differs in version between these two time‐\nstamps. debbisect can figure out which package is the culprit if you hand it control over in‐\nstalling dependencies for you via the --depends option. With that option active, the script\nwill not be responsible to set up a chroot itself but is given the path to an existing chroot\nas the first argument. Here is a real example that verifies the package responsible for De‐\nbian bug #912935:\n\n$ ./debbisect --depends=botch \"2018-11-17\" \"2018-11-22\" 'chroot \"$1\" botch-dose2html\n--packages=/dev/null --help'\n\n[...] test upgrading python3-minimal 3.6.7-1 -> 3.7.1-2...\n\nupgrading python3-minimal triggered the problem\n\nIf you want to run above test under qemu, then you would run:\n\n$ ./debbisect --depends=botch --qemu=defaults \"2018-11-17\" \"2018-11-22\" 'ssh -F \"$1\"\nqemu botch-dose2html --packages=/dev/null --help'\n\nIn the last two examples we omitted the --cache argument for brevity. But please make use of\nit to reduce the load on snapshot.debian.org.\n\n### AUTHOR\n\nWritten by Johannes Schauer Marin Rodrigues \n\n\n\ndebbisect 2.22.1ubuntu1.2 March 2026 DEBBISECT(1)\n\n" } ], "structuredContent": { "command": "debbisect", "section": "1", "mode": "man", "summary": "debbisect - bisect snapshot.debian.org", "synopsis": null, "flags": [ { "flag": "-h", "long": "--help", "arg": null, "description": "show this help message and exit" }, { "flag": "-d", "long": "--debug", "arg": null, "description": "Print lots of debugging statements" }, { "flag": "-v", "long": "--verbose", "arg": null, "description": "Be verbose --cache CACHE cache directory -- by default $TMPDIR is used" }, { "flag": "", "long": "--nocache", "arg": null, "description": "disable cache --port PORT manually choose port number for the apt cache instead of automatically choosing a free port --depends DEPENDS Comma separated list of binary packages the test script requires. With this option, the test script will run inside a chroot with the requested packages installed. --qemu QEMU Create qemu virtual machine and pass a ssh config file to the test script. This argu‐ ment takes a commaseparated series of key=value pairs to specify the virtual machine memory size (via memsize) and the virtual machine disksize (via disksize). Sizes are measured in bytes or with common unit suffixes like M or G. To pick the default values (disksize=4G,memsize=1G) the shorthand 'defaults' can be passed. --architecture ARCHITECTURE Chosen architecture when creating the chroot with --depends or --qemu (default: native architecture) --suite SUITE Chosen suite when creating the chroot with --depends or --qemu (default: unstable) --components COMPONENTS Chosen components (separated by comma or whitespace) when creating the chroot with --depends or --qemu (default: main)" }, { "flag": "", "long": "--no-find-exact-package", "arg": null, "description": "Normally, when the --depends argument is given so that debbisect takes care of manag‐ ing dependencies, the precise package that introduced the problem is determined after bisection by installing the packages that differ between the last good and first bad timestamp one by one. This option disables this feature." } ], "examples": [ "Just run \"dosomething\" which runs the test and returns a non-zero exit on failure.", "$ ./debbisect \"last week\" today \"mmdebstrap --customize-hook='chroot \\\"\\$1\\\" dosome‐", "thing' unstable - \\$DEBIANBISECTMIRROR >/dev/null\"", "$ diff -u debbisect.log.good debbisect.log.bad", "Since the command can easily become very long and quoting very involved, lets instead use a", "script:", "$ cat << END > script.sh", "> #!/bin/sh", "> set -exu", "> mmdebstrap \\", "> --verbose \\", "> --aptopt='Acquire::Check-Valid-Until \"false\"' \\", "> --variant=apt \\", "> --include=pkga,pkgb,pkgc \\", "> --customize-hook='chroot \"$1\" dpkg -l' \\", "> --customize-hook='chroot \"$1\" dosomething' \\", "> unstable \\", "> - \\", "> $DEBIANBISECTMIRROR \\", "> >/dev/null", "> END", "$ chmod +x script.sh", "$ ./debbisect --verbose --cache=./cache \"two years ago\" yesterday ./script.sh", "$ diff -u debbisect.log.good debbisect.log.bad", "$ rm -r ./cache", "This example sets Acquire::Check-Valid-Until to not fail on snapshot timestamps from \"two", "years ago\", uses the \"apt\" variant (only Essential:yes plus apt), installs the packages re‐", "quired for the test using --include, runs \"dpkg -l\" so that we can see which packages dif‐", "fered in the logs at the end and uses --cache=cache so that the apt cache does not get dis‐", "carded at the end and the command can be re-run without downloading everything from snap‐", "shot.debian.org again.", "If you want to build a source package you can use the script shipped by devscripts as", "/usr/share/doc/devscripts/examples/debbisectbuildsrc.sh and either use it unmodified like", "this:", "$ DEBIANBISECTSRCPKG=mysrc ./debbisect \"two years ago\" yesterday >", "/usr/share/doc/devscripts/examples/debbisectbuildsrc.sh", "or use the script as a starting point to do your own custom builds.", "Once debbisect has finished bisecting and figured out the last good and the first bad time‐", "stamp, there might be more than one package that differs in version between these two time‐", "stamps. debbisect can figure out which package is the culprit if you hand it control over in‐", "stalling dependencies for you via the --depends option. With that option active, the script", "will not be responsible to set up a chroot itself but is given the path to an existing chroot", "as the first argument. Here is a real example that verifies the package responsible for De‐", "bian bug #912935:", "$ ./debbisect --depends=botch \"2018-11-17\" \"2018-11-22\" 'chroot \"$1\" botch-dose2html", "--packages=/dev/null --help'", "[...] test upgrading python3-minimal 3.6.7-1 -> 3.7.1-2...", "upgrading python3-minimal triggered the problem", "If you want to run above test under qemu, then you would run:", "$ ./debbisect --depends=botch --qemu=defaults \"2018-11-17\" \"2018-11-22\" 'ssh -F \"$1\"", "qemu botch-dose2html --packages=/dev/null --help'", "In the last two examples we omitted the --cache argument for brevity. But please make use of", "it to reduce the load on snapshot.debian.org." ], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 29, "subsections": [ { "name": "positional arguments:", "lines": 9 }, { "name": "options:", "lines": 1 }, { "name": "-h --help", "lines": 2, "flag": "-h", "long": "--help" }, { "name": "-d --debug", "lines": 2, "flag": "-d", "long": "--debug" }, { "name": "-v --verbose", "lines": 5, "flag": "-v", "long": "--verbose" }, { "name": "--nocache", "lines": 28, "long": "--nocache" }, { "name": "--no-find-exact-package", "lines": 5, "long": "--no-find-exact-package" } ] }, { "name": "TIMESTAMPS", "lines": 18, "subsections": [] }, { "name": "ENVIRONMENT VARIABLES", "lines": 18, "subsections": [] }, { "name": "EXAMPLES", "lines": 70, "subsections": [] }, { "name": "AUTHOR", "lines": 5, "subsections": [] } ] } }