1NMBUG(1) notmuch NMBUG(1)
2
6 nmbug - manage notmuch bugs with git
7
9 notmuch git [-h] [-N] [-C repo] [-p prefix] [-v] [-l log level] subcom‐
10 mand
11 nmbug [-h] [-C repo] [-p prefix] [-v] [-l log level] subcommand
13
15 Manage notmuch tags with Git.
16 OPTIONS
18 Supported options for notmuch git include
19 -h, --help
21 show help message and exit
22 -N, --nmbug
24 Set defaults for --tag-prefix and --git-dir suitable for the
25 notmuch bug tracker
26 -C <repo>, --git-dir <repo>
28 Operate on git repository repo. See REPOSITORY LOCATION for de‐
29 faults.
30 -p <prefix>, --tag-prefix <prefix>
32 Operate only on tags with prefix prefix. See PREFIX VALUE for
33 defaults.
34 -v, --version
36 show notmuch-git's version number and exit
37 -l <level>, --log-level <level>
39 Log verbosity, one of: critical, error, warning, info, debug.
40 Defaults to warning.
41 SUBCOMMANDS
43 For help on a particular subcommand, run: 'notmuch-git ... <command>
44 --help'.
45 archive [tree-ish] [arg ...]
47 Dump a tar archive of a committed tag set using 'git archive'. See
49 REPOSITORY CONTENTS for details of the archive contents.
50 tree-ish
52 The tree or commit to produce an archive for. Defaults to 'HEAD'.
54 arg
56 If present, any optional arguments are passed through to git-ar‐
58 chive(1). Arguments to git-archive are reordered so that tree-ish
59 comes last.
60 checkout [-f|--force]
62 Update the notmuch database from Git.
64 This is mainly useful to discard your changes in notmuch relative to
66 Git.
67 [-f|--force]
69 Override checks that prevent modifying tags for large fractions of
71 messages in the database. See also git.safe_fraction.
72 clone <repository>
74 Create a local notmuch git repository from a remote source.
76 This wraps 'git clone', adding some options to avoid creating a working
78 tree while preserving remote-tracking branches and upstreams.
79 repository
81 The (possibly remote) repository to clone from. See the URLS section
83 of git-clone(1) for more information on specifying repositories.
84 commit [-f|--force] [message]
86 Commit prefix-matching tags from the notmuch database to Git.
88 message
90 Optional text for the commit message.
92 -f|--force
94 Override checks that prevent modifying tags for large fractions of
96 messages in the database. See also git.safe_fraction.
97 fetch [remote]
99 Fetch changes from the remote repository.
101 remote
103 Override the default configured in branch.<name>.remote to fetch
105 from a particular remote repository (e.g. origin).
106 help
108 Show brief help for an notmuch git command.
110 init [--format-version=N]
112 Create an empty notmuch git repository.
114 This wraps 'git init' with a few extra steps to support subsequent sta‐
116 tus and commit commands.
117 --format-version=N
119 Create a repo in format version N. By default notmuch-git uses the
121 highest supported version, which is the best choice for most
122 use-cases.
123 log [arg ...]
125 A wrapper for 'git log'.
127 arg
129 Additional arguments are passed through to 'git log'.
131 After running notmuch git fetch, you can inspect the changes with
133 $ notmuch git log HEAD..@{upstream}
135 merge [reference]
137 Merge changes from 'reference' into HEAD and load the result into not‐
139 much.
140 reference
142 Reference, usually other branch heads, to merge into our branch. De‐
144 faults to @{upstream}.
145 pull [repository] [refspec ...]
147 Pull (merge) remote repository changes to notmuch.
149 pull is equivalent to fetch followed by merge. We use the Git-config‐
151 ured repository for your current branch (branch.<name>.repository,
152 likely origin, and branch.<name>.merge, likely master or main).
153 repository
155 The "remote" repository that is the source of the pull. This parame‐
157 ter can be either a URL (see the section GIT URLS in git-pull(1)) or
158 the name of a remote (see the section REMOTES in git-pull(1)).
159 refspec
161 Refspec (usually a branch name) to fetch and merge. See the refspec
163 entry in the OPTIONS section of git-pull(1) for other possibilities.
164 push [repository] [refspec]
166 Push the local notmuch git Git state to a remote repository.
168 repository
170 The "remote" repository that is the destination of the push. This
172 parameter can be either a URL (see the section GIT URLS in
173 git-push(1)) or the name of a remote (see the section REMOTES in
174 git-push(1)).
175 refspec
177 Refspec (usually a branch name) to push. See the refspec entry in
179 the OPTIONS section of git-push(1) for other possibilities.
180 status
182 Show pending updates in notmuch or git repo.
184 Prints lines of the form
186 ng Message-Id tag
187 where n is a single character representing notmuch database status
190 A
192 Tag is present in notmuch database, but not committed to nmbug
194 (equivalently, tag has been deleted in nmbug repo, e.g. by a pull,
195 but not restored to notmuch database).
196 D
198 Tag is present in nmbug repo, but not restored to notmuch database
200 (equivalently, tag has been deleted in notmuch).
201 U
203 Message is unknown (missing from local notmuch database).
205 The second character g (if present) represents a difference between lo‐
207 cal and upstream branches. Typically notmuch git fetch needs to be run
208 to update this.
209 a
211 Tag is present in upstream, but not in the local Git branch.
213 d
215 Tag is present in local Git branch, but not upstream.
217
219 The tags are stored in the git repo (and exported) as a set of empty
220 files. These empty files are contained within a directory named after
221 the message-id.
222 In what follows encode() represents a POSIX filesystem safe encoding.
224 The encoding preserves alphanumerics, and the characters +-_@=.,:. All
225 other octets are replaced with % followed by a two digit hex number.
226 Currently notmuch-git can read any format version, but can only create
228 (via init) version 1 repositories.
229 Version 0
231 This is the legacy format created by the nmbug tool prior to release
232 0.37. For a message with Message-Id id, for each tag tag, there is an
233 empty file with path
234 tags/ encode (id) / encode (tag)
235 Version 1
237 In format version 1 and later, the format version is contained in a top
238 level file called FORMAT.
239 For a message with Message-Id id, for each tag tag, there is an empty
241 file with path
242 tags/ hash1 (id) / hash2 (id) encode (id) / encode (tag)
243 The hash functions each represent one byte of the blake2b hex digest.
245 Compared to version 0, this reduces the number of subdirectories within
247 each directory.
248
250 notmuch-git uses the first of the following with a non-empty value to
251 locate the git repository.
252 • Option --git-dir.
254 • Environment variable NOTMUCH_GIT_DIR.
256 • Configuration item git.path
258 • If invoked as nmbug or with the --nmbug option, $HOME/.nmbug; other‐
260 wise $XDG_DATA_HOME/notmuch/$NOTMUCH_PROFILE/git.
261
263 notmuch-git uses the first of the following with a non-null value to
264 define the tag prefix.
265 • Option --tag-prefix.
267 • Environment variable NOTMUCH_GIT_PREFIX.
269 • Configuration item git.tag_prefix.
271 • If invoked as nmbug or with the --nmbug option, notmuch::, otherwise
273 the empty string.
274
276 Variable NOTMUCH_PROFILE influences REPOSITORY LOCATION. If it is un‐
277 set, 'default' is assumed.
278 NOTMUCH_GIT_DIR
280 Default location of git repository. Overriden by --git-dir.
281 NOTMUCH_GIT_PREFIX
283 Default tag prefix (filter). Overriden by --tag-prefix.
284
286 notmuch, notmuch-dump, notmuch-restore, notmuch-tag
287
289 Carl Worth and many others
290
292 2009-2023, Carl Worth and many others
2930.37 Jan 19, 2023 NMBUG(1)