notmuch-git(1)

1NOTMUCH-GIT(1)                      notmuch                     NOTMUCH-GIT(1)
2
3
4

NAME

6       notmuch-git - manage notmuch tags with git
7

SYNOPSIS

9       notmuch git [-h] [-N] [-C repo] [-p prefix] [-v] [-l log level] subcom‐
10       mand
11
12       nmbug [-h] [-C repo] [-p prefix] [-v] [-l log level] subcommand
13

DESCRIPTION

15       Manage notmuch tags with Git.
16
17   OPTIONS
18       Supported options for notmuch git include
19
20       -h, --help
21              show help message and exit
22
23       -N, --nmbug
24              Set defaults for --tag-prefix and  --git-dir  suitable  for  the
25              notmuch bug tracker
26
27       -C <repo>, --git-dir <repo>
28              Operate  on git repository repo. See REPOSITORY LOCATION for de‐
29              faults.
30
31       -p <prefix>, --tag-prefix <prefix>
32              Operate only on tags with prefix prefix. See  PREFIX  VALUE  for
33              defaults.
34
35       -v, --version
36              show notmuch-git's version number and exit
37
38       -l <level>, --log-level <level>
39              Log  verbosity,  one  of: critical, error, warning, info, debug.
40              Defaults to warning.
41
42   SUBCOMMANDS
43       For help on a particular subcommand, run:  'notmuch-git  ...  <command>
44       --help'.
45
46       archive [tree-ish] [arg ...]
47
48       Dump  a  tar  archive  of  a committed tag set using 'git archive'. See
49       REPOSITORY CONTENTS for details of the archive contents.
50
51          tree-ish
52
53          The tree or commit to produce an archive for. Defaults to 'HEAD'.
54
55          arg
56
57          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
61       checkout [-f|--force]
62
63       Update the notmuch database from Git.
64
65       This is mainly useful to discard your changes in  notmuch  relative  to
66       Git.
67
68          [-f|--force]
69
70          Override  checks  that prevent modifying tags for large fractions of
71          messages in the database. See also git.safe_fraction.
72
73       clone <repository>
74
75       Create a local notmuch git repository from a remote source.
76
77       This wraps 'git clone', adding some options to avoid creating a working
78       tree while preserving remote-tracking branches and upstreams.
79
80          repository
81
82          The (possibly remote) repository to clone from. See the URLS section
83          of git-clone(1) for more information on specifying repositories.
84
85       commit [-f|--force] [message]
86
87       Commit prefix-matching tags from the notmuch database to Git.
88
89          message
90
91          Optional text for the commit message.
92
93          -f|--force
94
95          Override checks that prevent modifying tags for large  fractions  of
96          messages in the database. See also git.safe_fraction.
97
98       fetch [remote]
99
100       Fetch changes from the remote repository.
101
102          remote
103
104          Override  the  default  configured  in branch.<name>.remote to fetch
105          from a particular remote repository (e.g. origin).
106
107       help
108
109       Show brief help for an notmuch git command.
110
111       init [--format-version=N]
112
113       Create an empty notmuch git repository.
114
115       This wraps 'git init' with a few extra steps to support subsequent sta‐
116       tus and commit commands.
117
118          --format-version=N
119
120          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
124       log [arg ...]
125
126       A wrapper for 'git log'.
127
128          arg
129
130          Additional arguments are passed through to 'git log'.
131
132       After running notmuch git fetch, you can inspect the changes with
133
134          $ notmuch git log HEAD..@{upstream}
135
136       merge [reference]
137
138       Merge  changes from 'reference' into HEAD and load the result into not‐
139       much.
140
141          reference
142
143          Reference, usually other branch heads, to merge into our branch. De‐
144          faults to @{upstream}.
145
146       pull [repository] [refspec ...]
147
148       Pull (merge) remote repository changes to notmuch.
149
150       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
154          repository
155
156          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
160          refspec
161
162          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
165       push [repository] [refspec]
166
167       Push the local notmuch git Git state to a remote repository.
168
169          repository
170
171          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
176          refspec
177
178          Refspec  (usually  a  branch name) to push. See the refspec entry in
179          the OPTIONS section of git-push(1) for other possibilities.
180
181       status
182
183       Show pending updates in notmuch or git repo.
184
185       Prints lines of the form
186       ng Message-Id tag
187
188
189       where n is a single character representing notmuch database status
190
191          A
192
193          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
197          D
198
199          Tag is present in nmbug repo, but not restored to  notmuch  database
200          (equivalently, tag has been deleted in notmuch).
201
202          U
203
204          Message is unknown (missing from local notmuch database).
205
206       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
210          a
211
212          Tag is present in upstream, but not in the local Git branch.
213
214          d
215
216          Tag is present in local Git branch, but not upstream.
217

REPOSITORY CONTENTS

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
223       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
227       Currently  notmuch-git can read any format version, but can only create
228       (via init) version 1 repositories.
229
230   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
236   Version 1
237       In format version 1 and later, the format version is contained in a top
238       level file called FORMAT.
239
240       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
244       The hash functions each represent one byte of the blake2b hex digest.
245
246       Compared to version 0, this reduces the number of subdirectories within
247       each directory.
248

REPOSITORY LOCATION

250       notmuch-git  uses  the first of the following with a non-empty value to
251       locate the git repository.
252
253       • Option --git-dir.
254
255       • Environment variable NOTMUCH_GIT_DIR.
256
257       • Configuration item git.path
258
259       • If invoked as nmbug or with the --nmbug option, $HOME/.nmbug;  other‐
260         wise $XDG_DATA_HOME/notmuch/$NOTMUCH_PROFILE/git.
261

PREFIX VALUE

263       notmuch-git  uses  the  first of the following with a non-null value to
264       define the tag prefix.
265
266       • Option --tag-prefix.
267
268       • Environment variable NOTMUCH_GIT_PREFIX.
269
270       • Configuration item git.tag_prefix.
271
272       • If invoked as nmbug or with the --nmbug option, notmuch::,  otherwise
273         the empty string.
274

ENVIRONMENT

276       Variable  NOTMUCH_PROFILE influences REPOSITORY LOCATION.  If it is un‐
277       set, 'default' is assumed.
278
279       NOTMUCH_GIT_DIR
280              Default location of git repository. Overridden by --git-dir.
281
282       NOTMUCH_GIT_PREFIX
283              Default tag prefix (filter). Overridden by --tag-prefix.
284

AUTHOR

289       Carl Worth and many others
290

COPYRIGHT

292       2009-2023, Carl Worth and many others
293
294
295
296
2970.38                             Sep 12, 2023                   NOTMUCH-GIT(1)