10 **notmuch** **git** [-h] [-C *repo*] [-p *prefix*] [-v] [-l *log level*] *subcommand*
15 Manage notmuch tags with Git.
20 Supported options for `notmuch git` include
22 .. program:: notmuch-git
24 .. option:: -h, --help
26 show help message and exit
28 .. option:: -C <repo>, --git-dir <repo>
30 Operate on git repository *repo*. See :ref:`repo_location` for
33 .. option:: -p <prefix>, --tag-prefix <prefix>
35 Operate only on tags with prefix *prefix*. See :ref:`prefix_val` for
38 .. option:: -v, --version
40 show notmuch-git's version number and exit
42 .. option:: -l <level>, --log-level <level>
44 Log verbosity, one of: `critical`, `error`, `warning`, `info`,
45 `debug`. Defaults to `warning`.
50 For help on a particular subcommand, run: 'notmuch-git ... <command> --help'.
52 .. program:: notmuch-git
54 .. option:: archive [tree-ish] [arg ...]
56 Dump a tar archive of a committed tag set using 'git archive'. See
57 :any:`format` for details of the archive contents.
59 .. describe:: tree-ish
61 The tree or commit to produce an archive for. Defaults to 'HEAD'.
65 If present, any optional arguments are passed through to
66 :manpage:`git-archive(1)`. Arguments to `git-archive` are reordered
67 so that *tree-ish* comes last.
71 Update the notmuch database from Git.
73 This is mainly useful to discard your changes in notmuch relative
76 .. option:: clone <repository>
78 Create a local `notmuch git` repository from a remote source.
80 This wraps 'git clone', adding some options to avoid creating a
81 working tree while preserving remote-tracking branches and
84 .. describe:: repository
86 The (possibly remote) repository to clone from. See the URLS
87 section of :manpage:`git-clone(1)` for more information on
88 specifying repositories.
90 .. option:: commit [message]
92 Commit prefix-matching tags from the notmuch database to Git.
96 Optional text for the commit message.
98 .. option:: fetch [remote]
100 Fetch changes from the remote repository.
104 Override the default configured in `branch.<name>.remote` to fetch
105 from a particular remote repository (e.g. `origin`).
109 Show brief help for an `notmuch git` command.
113 Create an empty `notmuch git` repository.
115 This wraps 'git init' with a few extra steps to support subsequent
116 status and commit commands.
118 .. option:: log [arg ...]
120 A wrapper for 'git log'.
124 Additional arguments are passed through to 'git log'.
126 After running `notmuch git fetch`, you can inspect the changes with
130 $ notmuch git log HEAD..@{upstream}
132 .. option:: merge [reference]
134 Merge changes from 'reference' into HEAD and load the result into notmuch.
136 .. describe:: reference
138 Reference, usually other branch heads, to merge into our
139 branch. Defaults to `@{upstream}`.
141 .. option:: pull [repository] [refspec ...]
143 Pull (merge) remote repository changes to notmuch.
145 **pull** is equivalent to **fetch** followed by **merge**. We use the
146 Git-configured repository for your current branch
147 (`branch.<name>.repository`, likely `origin`, and `branch.<name>.merge`,
148 likely `master` or `main`).
150 .. describe:: repository
152 The "remote" repository that is the source of the pull. This parameter
153 can be either a URL (see the section GIT URLS in :manpage:`git-pull(1)`) or the
154 name of a remote (see the section REMOTES in :manpage:`git-pull(1)`).
156 .. describe:: refspec
158 Refspec (usually a branch name) to fetch and merge. See the
159 *refspec* entry in the OPTIONS section of :manpage:`git-pull(1`) for
162 .. option:: push [repository] [refspec]
164 Push the local `notmuch git` Git state to a remote repository.
166 .. describe:: repository
168 The "remote" repository that is the destination of the push. This
169 parameter can be either a URL (see the section GIT URLS in
170 :manpage:`git-push(1)`) or the name of a remote (see the section
171 REMOTES in :manpage:`git-push(1)`).
173 .. describe:: refspec
175 Refspec (usually a branch name) to push. See the *refspec* entry in the OPTIONS section of
176 :manpage:`git-push(1)` for other possibilities.
180 Show pending updates in notmuch or git repo.
182 Prints lines of the form
186 where n is a single character representing notmuch database status
190 Tag is present in notmuch database, but not committed to nmbug
191 (equivalently, tag has been deleted in nmbug repo, e.g. by a
192 pull, but not restored to notmuch database).
196 Tag is present in nmbug repo, but not restored to notmuch
197 database (equivalently, tag has been deleted in notmuch).
201 Message is unknown (missing from local notmuch database).
203 The second character *g* (if present) represents a difference between
204 local and upstream branches. Typically `notmuch git fetch` needs to be
209 Tag is present in upstream, but not in the local Git branch.
213 Tag is present in local Git branch, but not upstream.
220 The tags are stored in the git repo (and exported) as a set of empty
221 files. For a message with Message-Id *id*, for each tag *tag*, there
222 is an empty file with path
224 tags/ `encode` (*id*) / `encode` (*tag*)
226 The encoding preserves alphanumerics, and the characters `+-_@=.,:`.
227 All other octets are replaced with `%` followed by a two digit hex
235 :any:`notmuch-git` uses the first of the following with a non-empty
236 value to locate the git repository.
238 - Option :option:`--git-dir`.
240 - Environment variable :envvar:`NOTMUCH_GIT_DIR`.
247 :any:`notmuch-git` uses the first of the following with a non-null
248 value to define the tag prefix.
250 - Option :option:`--tag-prefix`.
252 - Environment variable :envvar:`NOTMUCH_GIT_PREFIX`.
257 .. envvar:: NOTMUCH_GIT_DIR
259 Default location of git repository. Overriden by :option:`--git-dir`.
261 .. envvar:: NOTMUCH_GIT_PREFIX
263 Default tag prefix (filter). Overriden by :option:`--tag-prefix`.
269 :any:`notmuch-dump(1)`,
270 :any:`notmuch-restore(1)`,
271 :any:`notmuch-tag(1)`