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.
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 .. option:: log [arg ...]
137 A wrapper for 'git log'.
141 Additional arguments are passed through to 'git log'.
143 After running `notmuch git fetch`, you can inspect the changes with
147 $ notmuch git log HEAD..@{upstream}
149 .. option:: merge [reference]
151 Merge changes from 'reference' into HEAD and load the result into notmuch.
153 .. describe:: reference
155 Reference, usually other branch heads, to merge into our
156 branch. Defaults to `@{upstream}`.
158 .. option:: pull [repository] [refspec ...]
160 Pull (merge) remote repository changes to notmuch.
162 **pull** is equivalent to **fetch** followed by **merge**. We use the
163 Git-configured repository for your current branch
164 (`branch.<name>.repository`, likely `origin`, and `branch.<name>.merge`,
165 likely `master` or `main`).
167 .. describe:: repository
169 The "remote" repository that is the source of the pull. This parameter
170 can be either a URL (see the section GIT URLS in :manpage:`git-pull(1)`) or the
171 name of a remote (see the section REMOTES in :manpage:`git-pull(1)`).
173 .. describe:: refspec
175 Refspec (usually a branch name) to fetch and merge. See the
176 *refspec* entry in the OPTIONS section of :manpage:`git-pull(1`) for
179 .. option:: push [repository] [refspec]
181 Push the local `notmuch git` Git state to a remote repository.
183 .. describe:: repository
185 The "remote" repository that is the destination of the push. This
186 parameter can be either a URL (see the section GIT URLS in
187 :manpage:`git-push(1)`) or the name of a remote (see the section
188 REMOTES in :manpage:`git-push(1)`).
190 .. describe:: refspec
192 Refspec (usually a branch name) to push. See the *refspec* entry in the OPTIONS section of
193 :manpage:`git-push(1)` for other possibilities.
197 Show pending updates in notmuch or git repo.
199 Prints lines of the form
203 where n is a single character representing notmuch database status
207 Tag is present in notmuch database, but not committed to nmbug
208 (equivalently, tag has been deleted in nmbug repo, e.g. by a
209 pull, but not restored to notmuch database).
213 Tag is present in nmbug repo, but not restored to notmuch
214 database (equivalently, tag has been deleted in notmuch).
218 Message is unknown (missing from local notmuch database).
220 The second character *g* (if present) represents a difference between
221 local and upstream branches. Typically `notmuch git fetch` needs to be
226 Tag is present in upstream, but not in the local Git branch.
230 Tag is present in local Git branch, but not upstream.
237 The tags are stored in the git repo (and exported) as a set of empty
238 files. For a message with Message-Id *id*, for each tag *tag*, there
239 is an empty file with path
241 tags/ `encode` (*id*) / `encode` (*tag*)
243 The encoding preserves alphanumerics, and the characters `+-_@=.,:`.
244 All other octets are replaced with `%` followed by a two digit hex
252 :any:`notmuch-git` uses the first of the following with a non-empty
253 value to locate the git repository.
255 - Option :option:`--git-dir`.
257 - Environment variable :envvar:`NOTMUCH_GIT_DIR`.
259 - Configuration item :nmconfig:`git.path`
261 - If invoked as `nmbug` or with the :option:`--nmbug` option,
262 :code:`$HOME/.nmbug`; otherwise
263 :code:`$XDG_DATA_HOME/notmuch/$NOTMUCH_PROFILE/git`.
270 :any:`notmuch-git` uses the first of the following with a non-null
271 value to define the tag prefix.
273 - Option :option:`--tag-prefix`.
275 - Environment variable :envvar:`NOTMUCH_GIT_PREFIX`.
277 - Configuration item :nmconfig:`git.tag_prefix`.
279 - If invoked as `nmbug` or with the :option:`--nmbug` option,
280 :code:`notmuch::`, otherwise the empty string.
285 Variable :envvar:`NOTMUCH_PROFILE` influences :ref:`repo_location`.
286 If it is unset, 'default' is assumed.
288 .. envvar:: NOTMUCH_GIT_DIR
290 Default location of git repository. Overriden by :option:`--git-dir`.
292 .. envvar:: NOTMUCH_GIT_PREFIX
294 Default tag prefix (filter). Overriden by :option:`--tag-prefix`.
300 :any:`notmuch-dump(1)`,
301 :any:`notmuch-restore(1)`,
302 :any:`notmuch-tag(1)`