Configuration

Nbdime uses a config system loosely based on that of Jupyter. This means that it looks for config files nbdime_config.json in all the directories listed by the jupyter --paths command, as well as the current working directory. The syntax of the config files are similar to that of other Jupyter commands:

{
  "NbDiff": {
    "details": false
  }
}

To list all the possible config options and their current effective values run the command:

nbdime --config

Alternatively, you can use the --config flag for any CLI entry point:

nbdiff --config
nbmerge --config

Any flags passed on the CLI will override the config value.

The current output of nbdime –config is:

All available config options, and their current values:

NbDiff:
  Ignore: {}
  attachments: null
  color_words: false
  details: null
  metadata: null
  outputs: null
  sources: null

NbDiffWeb:
  Ignore: {}
  attachments: null
  base_url: "/"
  browser: null
  color_words: false
  details: null
  ip: "127.0.0.1"
  metadata: null
  outputs: null
  persist: false
  port: 0
  sources: null
  workdirectory: ""

NbMerge:
  Ignore: {}
  attachments: null
  color_words: false
  details: null
  ignore_transients: true
  input_strategy: null
  merge_strategy: "inline"
  metadata: null
  output_strategy: null
  outputs: null
  sources: null

NbMergeWeb:
  Ignore: {}
  attachments: null
  base_url: "/"
  browser: null
  color_words: false
  details: null
  ignore_transients: true
  input_strategy: null
  ip: "127.0.0.1"
  merge_strategy: "inline"
  metadata: null
  output_strategy: null
  outputs: null
  persist: false
  port: 0
  sources: null
  workdirectory: ""

NbShow:
  Ignore: {}
  attachments: null
  details: null
  metadata: null
  outputs: null
  sources: null

Server:
  base_url: "/"
  browser: null
  ip: "127.0.0.1"
  persist: false
  port: 8888
  workdirectory: ""

Extension:
  Ignore: {}
  attachments: null
  color_words: false
  details: null
  metadata: null
  outputs: null
  sources: null

NbDiffDriver:
  Ignore: {}
  attachments: null
  color_words: false
  details: null
  metadata: null
  outputs: null
  sources: null

NbDiffTool:
  Ignore: {}
  attachments: null
  base_url: "/"
  browser: null
  color_words: false
  details: null
  ip: "127.0.0.1"
  metadata: null
  outputs: null
  persist: false
  port: 0
  sources: null
  workdirectory: ""

NbMergeDriver:
  Ignore: {}
  attachments: null
  color_words: false
  details: null
  ignore_transients: true
  input_strategy: null
  merge_strategy: "inline"
  metadata: null
  output_strategy: null
  outputs: null
  sources: null

NbMergeTool:
  Ignore: {}
  attachments: null
  base_url: "/"
  browser: null
  color_words: false
  details: null
  ignore_transients: true
  input_strategy: null
  ip: "127.0.0.1"
  merge_strategy: "inline"
  metadata: null
  output_strategy: null
  outputs: null
  persist: false
  port: 0
  sources: null
  workdirectory: ""

Sections

To make it easier to configure the options of several commands at the same time, you can use the following config sections:

Global

Options to apply to all commands, only for options that are supported by all commands

Web

Options to web commands (Server, NbDiffWeb, NbMergeWeb, NbDiffTool, NbMergeTool).

WebTool

Options to web tool commands (NbDiffTool, NbMergeTool).

Diff

Options to diffing commands (NbDiff, NbDiffWeb, NbDiffDriver, NbDiffTool, Extension).

Merge

Options to merge commands (NbMerge, NbMergeWeb, NbMergeDriver, NbMergeTool).

GitDiff

Options to git diff commands (NbDiff, NbDiffWeb, NbDiffDriver, NbDiffTool, Extension)

GitMerge

Options to git diff commands (NbMergeDriver, NbMergeTool)

Note

These sections are ways to configure several commands / entrypoints at once. The individual command names are the once listed in parantheses at the end of the sections, or can be seen by running nbdime --config.

Configuring ignores

The config system allows for detailed control over what to ignore or not via the “Ignore” key. It takes a dictionary in the following format:

"Ignore": {
  "/cells/*/outputs": true,
  "/cells/*/attachments": false,
  "/cells/*/metadata": ["collapsed", "autoscroll", "deletable", "editable"]
}

Which will ignore outputs, specify that attachments should not be ignored, and ignore the cell metadata keys as specified in the list. In general, true and false are used to configure diffing an entire list or map (e.g. "/cells/*/outputs" is a list of output, and "/cells/*/metadata" is a map of key-value pairs). For maps, you can additionally specify a list of keys to ignore. This is meant to enable ignoring of leaf-nodes like execution_count on cells and outputs, or specific metadata keys. If the key is not a leaf-node, it is recommended to instead include the key in the path, and use true or false.

Configurations of “Ignore” in different sections will be merged, such that non-conflicting keys will all be added. If the keys (diff paths) overlap, the most specific section’s value will be taken. As an example, take the following config:

{
  "Diff": {
    "Ignore": {
      "/metadata": ["foo"],
      "/cells/*/metadata": ["tags"]
    }
  },
  "GitDiff": {
    "Ignore": {
      "/cells/*/outputs": true,
      "/cells/*/metadata": ["collapsed", "autoscroll", "deletable", "editable"]
    }
  }
}

Here, the final config for a git diff entry point will be:

{
  "Ignore": {
    "/metadata": ["foo"],
    "/cells/*/outputs": true,
    "/cells/*/metadata": ["collapsed", "autoscroll", "deletable", "editable"]
  }
}

This means that the “tags” entry from the “Diff” section is not automatically included in the merge.

Front-end extensions

The configuration of the diffing for the front-end extensions (notebook and lab) is controlled by the section key “Extension”. For extensions, nbdime is not launched as a separate process, but is called as a server extension. For this reason, any of config options that conflict with those of the lab/notebook process are ignored.