10 **notmuch** **git** [-h] [-N] [-C *repo*] [-p *prefix*] [-v] [-l *log level*] *subcommand*
12 **nmbug** [-h] [-C *repo*] [-p *prefix*] [-v] [-l *log level*] *subcommand*
17 Manage notmuch tags with Git.
22 Supported options for `notmuch git` include
24 .. program:: notmuch-git
26 .. option:: -h, --help
28 show help message and exit
30 .. option:: -N, --nmbug
32 Set defaults for :option:`--tag-prefix` and :option:`--git-dir` suitable for the
33 :any:`notmuch` bug tracker
35 .. option:: -C <repo>, --git-dir <repo>
37 Operate on git repository *repo*. See :ref:`repo_location` for
40 .. option:: -p <prefix>, --tag-prefix <prefix>
42 Operate only on tags with prefix *prefix*. See :ref:`prefix_val` for
45 .. option:: -v, --version
47 show notmuch-git's version number and exit
49 .. option:: -l <level>, --log-level <level>
51 Log verbosity, one of: `critical`, `error`, `warning`, `info`,
52 `debug`. Defaults to `warning`.
57 For help on a particular subcommand, run: 'notmuch-git ... <command> --help'.
59 .. program:: notmuch-git
61 .. option:: archive [tree-ish] [arg ...]
63 Dump a tar archive of a committed tag set using 'git archive'. See
64 :any:`format` for details of the archive contents.
66 .. describe:: tree-ish
68 The tree or commit to produce an archive for. Defaults to 'HEAD'.
72 If present, any optional arguments are passed through to
73 :manpage:`git-archive(1)`. Arguments to `git-archive` are reordered
74 so that *tree-ish* comes last.
76 .. option:: checkout [-f|--force]
78 Update the notmuch database from Git.
80 This is mainly useful to discard your changes in notmuch relative
83 .. describe:: [-f|--force]
85 Override checks that prevent modifying tags for large fractions of
86 messages in the database. See also :nmconfig:`git.safe_fraction`.
88 .. option:: clone <repository>
90 Create a local `notmuch git` repository from a remote source.
92 This wraps 'git clone', adding some options to avoid creating a
93 working tree while preserving remote-tracking branches and
96 .. describe:: repository
98 The (possibly remote) repository to clone from. See the URLS
99 section of :manpage:`git-clone(1)` for more information on
100 specifying repositories.
102 .. option:: commit [-f|--force] [message]
104 Commit prefix-matching tags from the notmuch database to Git.
106 .. describe:: message
108 Optional text for the commit message.
110 .. describe:: -f|--force
112 Override checks that prevent modifying tags for large fractions of
113 messages in the database. See also :nmconfig:`git.safe_fraction`.
115 .. option:: fetch [remote]
117 Fetch changes from the remote repository.
121 Override the default configured in `branch.<name>.remote` to fetch
122 from a particular remote repository (e.g. `origin`).
126 Show brief help for an `notmuch git` command.
128 .. option:: init [--format-version=N]
130 Create an empty `notmuch git` repository.
132 This wraps 'git init' with a few extra steps to support subsequent
133 status and commit commands.
135 .. describe:: --format-version=N
137 Create a repo in format version N. By default :any:`notmuch-git`
138 uses the highest supported version, which is the best choice for
141 .. option:: log [arg ...]
143 A wrapper for 'git log'.
147 Additional arguments are passed through to 'git log'.
149 After running `notmuch git fetch`, you can inspect the changes with
153 $ notmuch git log HEAD..@{upstream}
155 .. option:: merge [reference]
157 Merge changes from 'reference' into HEAD and load the result into notmuch.
159 .. describe:: reference
161 Reference, usually other branch heads, to merge into our
162 branch. Defaults to `@{upstream}`.
164 .. option:: pull [repository] [refspec ...]
166 Pull (merge) remote repository changes to notmuch.
168 **pull** is equivalent to **fetch** followed by **merge**. We use the
169 Git-configured repository for your current branch
170 (`branch.<name>.repository`, likely `origin`, and `branch.<name>.merge`,
171 likely `master` or `main`).
173 .. describe:: repository
175 The "remote" repository that is the source of the pull. This parameter
176 can be either a URL (see the section GIT URLS in :manpage:`git-pull(1)`) or the
177 name of a remote (see the section REMOTES in :manpage:`git-pull(1)`).
179 .. describe:: refspec
181 Refspec (usually a branch name) to fetch and merge. See the
182 *refspec* entry in the OPTIONS section of :manpage:`git-pull(1`) for
185 .. option:: push [repository] [refspec]
187 Push the local `notmuch git` Git state to a remote repository.
189 .. describe:: repository
191 The "remote" repository that is the destination of the push. This
192 parameter can be either a URL (see the section GIT URLS in
193 :manpage:`git-push(1)`) or the name of a remote (see the section
194 REMOTES in :manpage:`git-push(1)`).
196 .. describe:: refspec
198 Refspec (usually a branch name) to push. See the *refspec* entry in the OPTIONS section of
199 :manpage:`git-push(1)` for other possibilities.
203 Show pending updates in notmuch or git repo.
205 Prints lines of the form
209 where n is a single character representing notmuch database status
213 Tag is present in notmuch database, but not committed to nmbug
214 (equivalently, tag has been deleted in nmbug repo, e.g. by a
215 pull, but not restored to notmuch database).
219 Tag is present in nmbug repo, but not restored to notmuch
220 database (equivalently, tag has been deleted in notmuch).
224 Message is unknown (missing from local notmuch database).
226 The second character *g* (if present) represents a difference between
227 local and upstream branches. Typically `notmuch git fetch` needs to be
232 Tag is present in upstream, but not in the local Git branch.
236 Tag is present in local Git branch, but not upstream.
243 The tags are stored in the git repo (and exported) as a set of empty
244 files. These empty files are contained within a directory named after
247 In what follows `encode()` represents a POSIX filesystem safe
248 encoding. The encoding preserves alphanumerics, and the characters
249 `+-_@=.,:`. All other octets are replaced with `%` followed by a two
252 Currently :any:`notmuch-git` can read any format version, but can only
253 create (via :any:`init`) :ref:`version 1 <format_version_1>` repositories.
255 .. _format_version_0:
260 This is the legacy format created by the `nmbug` tool prior to release
261 0.37. For a message with Message-Id *id*, for each tag *tag*, there
262 is an empty file with path
264 tags/ `encode` (*id*) / `encode` (*tag*)
266 .. _format_version_1:
271 In format version 1 and later, the format version is contained in a
272 top level file called FORMAT.
274 For a message with Message-Id *id*, for each tag *tag*, there
275 is an empty file with path
277 tags/ `hash1` (*id*) / `hash2` (*id*) `encode` (*id*) / `encode` (*tag*)
279 The hash functions each represent one byte of the `blake2b` hex
282 Compared to :ref:`version 0 <format_version_0>`, this reduces the
283 number of subdirectories within each directory.
290 :any:`notmuch-git` uses the first of the following with a non-empty
291 value to locate the git repository.
293 - Option :option:`--git-dir`.
295 - Environment variable :envvar:`NOTMUCH_GIT_DIR`.
297 - Configuration item :nmconfig:`git.path`
299 - If invoked as `nmbug` or with the :option:`--nmbug` option,
300 :code:`$HOME/.nmbug`; otherwise
301 :code:`$XDG_DATA_HOME/notmuch/$NOTMUCH_PROFILE/git`.
308 :any:`notmuch-git` uses the first of the following with a non-null
309 value to define the tag prefix.
311 - Option :option:`--tag-prefix`.
313 - Environment variable :envvar:`NOTMUCH_GIT_PREFIX`.
315 - Configuration item :nmconfig:`git.tag_prefix`.
317 - If invoked as `nmbug` or with the :option:`--nmbug` option,
318 :code:`notmuch::`, otherwise the empty string.
323 Variable :envvar:`NOTMUCH_PROFILE` influences :ref:`repo_location`.
324 If it is unset, 'default' is assumed.
326 .. envvar:: NOTMUCH_GIT_DIR
328 Default location of git repository. Overridden by :option:`--git-dir`.
330 .. envvar:: NOTMUCH_GIT_PREFIX
332 Default tag prefix (filter). Overridden by :option:`--tag-prefix`.
338 :any:`notmuch-dump(1)`,
339 :any:`notmuch-restore(1)`,
340 :any:`notmuch-tag(1)`