Package: nbstripout
Severity: normal
Tags: patch
X-Debbugs-Cc: francesco.balla...@unicatt.it, p...@debian.org
Hi,
the following patch adds a manpage to the nbstripout executable.
The same patch is in the following commit in the experimental branch on salsa
at the link
https://salsa.debian.org/python-team/packages/python-nbstripout/-/commit/54e1cd94b347897478728510605a385a5cdd7662
Francesco
.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3.
.TH NBSTRIPOUT "1" "July 2025" "nbstripout 0.8.1" "User Commands"
.SH NAME
nbstripout \- strip output from Jupyter and IPython notebooks
.SH DESCRIPTION
usage: nbstripout [\-h] [\-\-dry\-run | \fB\-\-install\fR | \fB\-\-uninstall\fR
| \fB\-\-is\-installed\fR |
.IP
\fB\-\-status\fR | \fB\-\-version]\fR [\-\-verify] [\-\-keep\-count]
[\-\-keep\-output] [\-\-keep\-id] [\-\-extra\-keys EXTRA_KEYS]
[\-\-keep\-metadata\-keys KEEP_METADATA_KEYS]
[\-\-drop\-empty\-cells] [\-\-drop\-tagged\-cells DROP_TAGGED_CELLS]
[\-\-strip\-init\-cells] [\-\-attributes FILEPATH] [\-\-global |
\fB\-\-system\fR | \fB\-\-python\fR PATH] [\-\-force] [\-\-max\-size SIZE]
[\-\-mode {jupyter,zeppelin}] [\-\-textconv]
[files ...]
.SS "positional arguments:"
.TP
files
Files to strip output from
.SS "options:"
.TP
\fB\-h\fR, \fB\-\-help\fR
show this help message and exit
.TP
\fB\-\-dry\-run\fR
Print which notebooks would have been stripped
.TP
\fB\-\-install\fR
Install nbstripout in the current repository (set up
the git filter and attributes)
.TP
\fB\-\-uninstall\fR
Uninstall nbstripout from the current repository
(remove the git filter and attributes)
.TP
\fB\-\-is\-installed\fR
Check if nbstripout is installed in current repository
.TP
\fB\-\-status\fR
Print status of nbstripout installation in current
repository and configuration summary if installed
.TP
\fB\-\-version\fR
Print version
.TP
\fB\-\-verify\fR
Return a non\-zero exit code if any files were changed,
Implies \fB\-\-dry\-run\fR
.TP
\fB\-\-keep\-count\fR
Do not strip the execution count/prompt number
.TP
\fB\-\-keep\-output\fR
Do not strip output
.TP
\fB\-\-keep\-id\fR
Keep the randomly generated cell ids, which will be
different after each execution.
.TP
\fB\-\-extra\-keys\fR EXTRA_KEYS
Space separated list of extra keys to strip from
metadata, e.g. metadata.foo cell.metadata.bar
.TP
\fB\-\-keep\-metadata\-keys\fR KEEP_METADATA_KEYS
Space separated list of metadata keys to keep, e.g.
metadata.foo cell.metadata.bar
.TP
\fB\-\-drop\-empty\-cells\fR
Remove cells where `source` is empty or contains only
whitepace
.TP
\fB\-\-drop\-tagged\-cells\fR DROP_TAGGED_CELLS
Space separated list of cell\-tags that remove an
entire cell
.TP
\fB\-\-strip\-init\-cells\fR
Remove cells with `init_cell: true` metadata (default:
False)
.TP
\fB\-\-attributes\fR FILEPATH
Attributes file to add the filter to (in combination
with \fB\-\-install\fR/\-\-uninstall), defaults to
\&.git/info/attributes
.TP
\fB\-\-global\fR
Use global git config (default is local config)
.TP
\fB\-\-system\fR
Use system git config (default is local config)
.TP
\fB\-\-python\fR PATH
Path to python executable to use when \fB\-\-install\fR'ing
(default is deduced from `sys.executable`)
.TP
\fB\-\-force\fR, \fB\-f\fR
Strip output also from files with non ipynb extension
.TP
\fB\-\-max\-size\fR SIZE
Keep outputs smaller than SIZE
.TP
\fB\-\-mode\fR, \fB\-m\fR {jupyter,zeppelin}
Specify mode between [jupyter (default) | zeppelin]
(to be used in combination with \fB\-f\fR)
.TP
\fB\-\-textconv\fR, \fB\-t\fR
Prints stripped files to STDOUT
.PP
Strip output from Jupyter and IPython notebooks
===============================================
.PP
Opens a notebook, strips its output, and writes the outputless version to the
original file.
.PP
Useful mainly as a git filter or pre\-commit hook for users who don't want to
track output in VCS.
.PP
This does mostly the same thing as the `Clear All Output` command in the
notebook UI.
.PP
Usage
=====
.PP
Strip output from IPython / Jupyter / Zeppelin notebook (modifies the file
in\-place): ::
.IP
nbstripout <file.ipynb>
nbstripout <file.zpln>
.PP
By default, nbstripout will only modify files ending in '.ipynb' or '.zpln', to
process other files us the '\-f' flag to force the application.
.IP
nbstripout \fB\-f\fR <file.ipynb.bak>
.SS "For using Zeppelin mode while processing files with other extensions use:"
.IP
nbstripout \fB\-m\fR zeppelin \fB\-f\fR <file.ext>
.PP
Use as part of a shell pipeline: ::
.IP
cat FILE.ipynb | nbstripout > OUT.ipynb
cat FILE.zpln | nbstripout \fB\-m\fR zeppelin > OUT.zpln
.PP
Set up the git filter and attributes as described in the manual installation
instructions below: ::
.IP
nbstripout \fB\-\-install\fR
.PP
Set up the git filter using ``.gitattributes`` ::
.IP
nbstripout \fB\-\-install\fR \fB\-\-attributes\fR .gitattributes
.PP
Set up the git filter in your global ``~/.gitconfig`` ::
.IP
nbstripout \fB\-\-install\fR \fB\-\-global\fR
.PP
Set up the git filter in your system\-wide ``$(prefix)/etc/gitconfig`` (most
installations will require you to ``sudo``) ::
.IP
[sudo] nbstripout \fB\-\-install\fR \fB\-\-system\fR
.PP
Remove the git filter and attributes: ::
.IP
nbstripout \fB\-\-uninstall\fR
.PP
Remove the git filter from your global ``~/.gitconfig`` and attributes ::
.IP
nbstripout \fB\-\-uninstall\fR \fB\-\-global\fR
.PP
Remove the git filter from your system\-wide ``$(prefix)/etc/gitconfig`` and
attributes ::
.IP
nbstripout \fB\-\-uninstall\fR \fB\-\-system\fR
.PP
Remove the git filter and attributes from ``.gitattributes``: ::
.IP
nbstripout \fB\-\-uninstall\fR \fB\-\-attributes\fR .gitattributes
.PP
Check if ``nbstripout`` is installed in the current repository
(exits with code 0 if installed, 1 otherwise): ::
.IP
nbstripout \fB\-\-is\-installed\fR
.PP
Print status of ``nbstripout`` installation in the current repository and
configuration summary of filter and attributes if installed
(exits with code 0 if installed, 1 otherwise): ::
.IP
nbstripout \fB\-\-status\fR
.PP
Do a dry run and only list which files would have been stripped: ::
.IP
nbstripout \fB\-\-dry\-run\fR FILE.ipynb [FILE2.ipynb ...]
.PP
Print the version: ::
.IP
nbstripout \fB\-\-version\fR
.PP
Show this help page: ::
.IP
nbstripout \fB\-\-help\fR
.PP
Manual filter installation
==========================
.PP
Set up a git filter using nbstripout as follows: ::
.IP
git config filter.nbstripout.clean '/path/to/nbstripout'
git config filter.nbstripout.smudge cat
.PP
Create a file ``.gitattributes`` or ``.git/info/attributes`` with: ::
.IP
*.ipynb filter=nbstripout
.PP
Apply the filter for git diff of ``*.ipynb`` files: ::
.IP
git config diff.ipynb.textconv '/path/to/nbstripout \fB\-t\fR'
.PP
In file ``.gitattributes`` or ``.git/info/attributes`` add: ::
.IP
*.ipynb diff=ipynb
