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.
78 Update the notmuch database from Git.
80 This is mainly useful to discard your changes in notmuch relative
83 .. option:: clone <repository>
85 Create a local `notmuch git` repository from a remote source.
87 This wraps 'git clone', adding some options to avoid creating a
88 working tree while preserving remote-tracking branches and
91 .. describe:: repository
93 The (possibly remote) repository to clone from. See the URLS
94 section of :manpage:`git-clone(1)` for more information on
95 specifying repositories.
97 .. option:: commit [message]
99 Commit prefix-matching tags from the notmuch database to Git.
101 .. describe:: message
103 Optional text for the commit message.
105 .. option:: fetch [remote]
107 Fetch changes from the remote repository.
111 Override the default configured in `branch.<name>.remote` to fetch
112 from a particular remote repository (e.g. `origin`).
116 Show brief help for an `notmuch git` command.
120 Create an empty `notmuch git` repository.
122 This wraps 'git init' with a few extra steps to support subsequent
123 status and commit commands.
125 .. option:: log [arg ...]
127 A wrapper for 'git log'.
131 Additional arguments are passed through to 'git log'.
133 After running `notmuch git fetch`, you can inspect the changes with
137 $ notmuch git log HEAD..@{upstream}
139 .. option:: merge [reference]
141 Merge changes from 'reference' into HEAD and load the result into notmuch.
143 .. describe:: reference
145 Reference, usually other branch heads, to merge into our
146 branch. Defaults to `@{upstream}`.
148 .. option:: pull [repository] [refspec ...]
150 Pull (merge) remote repository changes to notmuch.
152 **pull** is equivalent to **fetch** followed by **merge**. We use the
153 Git-configured repository for your current branch
154 (`branch.<name>.repository`, likely `origin`, and `branch.<name>.merge`,
155 likely `master` or `main`).
157 .. describe:: repository
159 The "remote" repository that is the source of the pull. This parameter
160 can be either a URL (see the section GIT URLS in :manpage:`git-pull(1)`) or the
161 name of a remote (see the section REMOTES in :manpage:`git-pull(1)`).
163 .. describe:: refspec
165 Refspec (usually a branch name) to fetch and merge. See the
166 *refspec* entry in the OPTIONS section of :manpage:`git-pull(1`) for
169 .. option:: push [repository] [refspec]
171 Push the local `notmuch git` Git state to a remote repository.
173 .. describe:: repository
175 The "remote" repository that is the destination of the push. This
176 parameter can be either a URL (see the section GIT URLS in
177 :manpage:`git-push(1)`) or the name of a remote (see the section
178 REMOTES in :manpage:`git-push(1)`).
180 .. describe:: refspec
182 Refspec (usually a branch name) to push. See the *refspec* entry in the OPTIONS section of
183 :manpage:`git-push(1)` for other possibilities.
187 Show pending updates in notmuch or git repo.
189 Prints lines of the form
193 where n is a single character representing notmuch database status
197 Tag is present in notmuch database, but not committed to nmbug
198 (equivalently, tag has been deleted in nmbug repo, e.g. by a
199 pull, but not restored to notmuch database).
203 Tag is present in nmbug repo, but not restored to notmuch
204 database (equivalently, tag has been deleted in notmuch).
208 Message is unknown (missing from local notmuch database).
210 The second character *g* (if present) represents a difference between
211 local and upstream branches. Typically `notmuch git fetch` needs to be
216 Tag is present in upstream, but not in the local Git branch.
220 Tag is present in local Git branch, but not upstream.
227 The tags are stored in the git repo (and exported) as a set of empty
228 files. For a message with Message-Id *id*, for each tag *tag*, there
229 is an empty file with path
231 tags/ `encode` (*id*) / `encode` (*tag*)
233 The encoding preserves alphanumerics, and the characters `+-_@=.,:`.
234 All other octets are replaced with `%` followed by a two digit hex
242 :any:`notmuch-git` uses the first of the following with a non-empty
243 value to locate the git repository.
245 - Option :option:`--git-dir`.
247 - Environment variable :envvar:`NOTMUCH_GIT_DIR`.
249 - Configuration item :nmconfig:`git.path`
251 - If invoked as `nmbug` or with the :option:`--nmbug` option,
252 :code:`$HOME/.nmbug`; otherwise
253 :code:`$XDG_DATA_HOME/notmuch/$NOTMUCH_PROFILE/git`.
260 :any:`notmuch-git` uses the first of the following with a non-null
261 value to define the tag prefix.
263 - Option :option:`--tag-prefix`.
265 - Environment variable :envvar:`NOTMUCH_GIT_PREFIX`.
267 - Configuration item :nmconfig:`git.tag_prefix`.
269 - If invoked as `nmbug` or with the :option:`--nmbug` option,
270 :code:`notmuch::`, otherwise the empty string.
275 Variable :envvar:`NOTMUCH_PROFILE` influences :ref:`repo_location`.
276 If it is unset, 'default' is assumed.
278 .. envvar:: NOTMUCH_GIT_DIR
280 Default location of git repository. Overriden by :option:`--git-dir`.
282 .. envvar:: NOTMUCH_GIT_PREFIX
284 Default tag prefix (filter). Overriden by :option:`--tag-prefix`.
290 :any:`notmuch-dump(1)`,
291 :any:`notmuch-restore(1)`,
292 :any:`notmuch-tag(1)`