relative to the repository root (this was the default for git
prior to v1.5.4).
+status.showUntrackedFiles::
+ By default, linkgit:git-status[1] and linkgit:git-commit[1] show
+ files which are not currently tracked by Git. Directories which
+ contain only untracked files, are shown with the directory name
+ only. Showing untracked files means that Git needs to lstat() all
+ all the files in the whole repository, which might be slow on some
+ systems. So, this variable controls how the commands displays
+ the untracked files. Possible values are:
++
+--
+ - 'no' - Show no untracked files
+ - 'normal' - Shows untracked files and directories
+ - 'all' - Shows also individual files in untracked directories.
+--
++
+If this variable is not specified, it defaults to 'normal'.
+This variable can be overridden with the -u|--untracked-files option
+of linkgit:git-status[1] and linkgit:git-commit[1].
+
tar.umask::
This variable can be used to restrict the permission bits of
tar archive entries. The default is 0002, which turns off the
<h2>SYNOPSIS</h2>\r
<div class="sectionbody">\r
<div class="verseblock">\r
-<div class="content"><em>git-commit</em> [-a | --interactive] [-s] [-v] [-u] [--amend]\r
+<div class="content"><em>git-commit</em> [-a | --interactive] [-s] [-v] [-u<mode>] [--amend]\r
[(-c | -C) <commit>] [-F <file> | -m <msg>]\r
[--allow-empty] [--no-verify] [-e] [--author=<author>]\r
[--cleanup=<mode>] [--] [[-i | -o ]<file>…]</div></div>\r
</p>\r
</dd>\r
<dt>\r
--u\r
+-u[<mode>]\r
</dt>\r
<dt>\r
---untracked-files\r
+--untracked-files[=<mode>]\r
</dt>\r
<dd>\r
<p>\r
- Show all untracked files, also those in uninteresting\r
- directories, in the "Untracked files:" section of commit\r
- message template. Without this option only its name and\r
- a trailing slash are displayed for each untracked\r
- directory.\r
+ Show untracked files (Default: <em>all</em>).\r
</p>\r
+<p>The mode parameter is optional, and is used to specify\r
+the handling of untracked files. The possible options are:</p>\r
+<ul>\r
+<li>\r
+<p>\r
+<em>no</em> - Show no untracked files\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<em>normal</em> - Shows untracked files and directories\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<em>all</em> - Also shows individual files in untracked directories.\r
+</p>\r
+</li>\r
+</ul>\r
+<p>See <a href="git-config.html">git-config(1)</a> for configuration variable\r
+used to change the default for when the option is not\r
+specified.</p>\r
</dd>\r
<dt>\r
-v\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 08-Jun-2008 22:46:24 UTC\r
+Last updated 23-Jun-2008 07:13:34 UTC\r
</div>\r
</div>\r
</body>\r
SYNOPSIS
--------
[verse]
-'git-commit' [-a | --interactive] [-s] [-v] [-u] [--amend]
+'git-commit' [-a | --interactive] [-s] [-v] [-u<mode>] [--amend]
[(-c | -C) <commit>] [-F <file> | -m <msg>]
[--allow-empty] [--no-verify] [-e] [--author=<author>]
[--cleanup=<mode>] [--] [[-i | -o ]<file>...]
the last commit without committing changes that have
already been staged.
--u::
---untracked-files::
- Show all untracked files, also those in uninteresting
- directories, in the "Untracked files:" section of commit
- message template. Without this option only its name and
- a trailing slash are displayed for each untracked
- directory.
+-u[<mode>]::
+--untracked-files[=<mode>]::
+ Show untracked files (Default: 'all').
++
+The mode parameter is optional, and is used to specify
+the handling of untracked files. The possible options are:
++
+--
+ - 'no' - Show no untracked files
+ - 'normal' - Shows untracked files and directories
+ - 'all' - Also shows individual files in untracked directories.
+--
++
+See linkgit:git-config[1] for configuration variable
+used to change the default for when the option is not
+specified.
-v::
--verbose::
</p>\r
</dd>\r
<dt>\r
+status.showUntrackedFiles\r
+</dt>\r
+<dd>\r
+<p>\r
+ By default, <a href="git-status.html">git-status(1)</a> and <a href="git-commit.html">git-commit(1)</a> show\r
+ files which are not currently tracked by Git. Directories which\r
+ contain only untracked files, are shown with the directory name\r
+ only. Showing untracked files means that Git needs to lstat() all\r
+ all the files in the whole repository, which might be slow on some\r
+ systems. So, this variable controls how the commands displays\r
+ the untracked files. Possible values are:\r
+</p>\r
+<ul>\r
+<li>\r
+<p>\r
+<em>no</em> - Show no untracked files\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<em>normal</em> - Shows untracked files and directories\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<em>all</em> - Shows also individual files in untracked directories.\r
+</p>\r
+</li>\r
+</ul>\r
+<p>If this variable is not specified, it defaults to <em>normal</em>.\r
+This variable can be overridden with the -u|--untracked-files option\r
+of <a href="git-status.html">git-status(1)</a> and <a href="git-commit.html">git-commit(1)</a>.</p>\r
+</dd>\r
+<dt>\r
tar.umask\r
</dt>\r
<dd>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 08-Jun-2008 22:46:25 UTC\r
+Last updated 23-Jun-2008 07:13:34 UTC\r
</div>\r
</div>\r
</body>\r
unsigned, with <em>verbatim</em>, they will be silently exported\r
and with <em>warn</em>, they will be exported, but you will see a warning.</p>\r
</dd>\r
+<dt>\r
+--export-marks=<file>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Dumps the internal marks table to <file> when complete.\r
+ Marks are written one per line as <tt>:markid SHA-1</tt>. Only marks\r
+ for revisions are dumped; marks for blobs are ignored.\r
+ Backends can use this file to validate imports after they\r
+ have been completed, or to save the marks table across\r
+ incremental runs. As <file> is only opened and truncated\r
+ at completion, the same path can also be safely given to\r
+ --import-marks.\r
+</p>\r
+</dd>\r
+<dt>\r
+--import-marks=<file>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Before processing any input, load the marks specified in\r
+ <file>. The input file must exist, must be readable, and\r
+ must use the same format as produced by --export-marks.\r
+</p>\r
+<p>Any commits that have already been marked will not be exported again.\r
+If the backend uses a similar --import-marks file, this allows for\r
+incremental bidirectional exporting of the repository by keeping the\r
+marks the same across runs.</p>\r
+</dd>\r
</dl>\r
</div>\r
<h2>EXAMPLES</h2>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 08-Jun-2008 01:33:37 UTC\r
+Last updated 23-Jun-2008 07:13:35 UTC\r
</div>\r
</div>\r
</body>\r
unsigned, with 'verbatim', they will be silently exported
and with 'warn', they will be exported, but you will see a warning.
+--export-marks=<file>::
+ Dumps the internal marks table to <file> when complete.
+ Marks are written one per line as `:markid SHA-1`. Only marks
+ for revisions are dumped; marks for blobs are ignored.
+ Backends can use this file to validate imports after they
+ have been completed, or to save the marks table across
+ incremental runs. As <file> is only opened and truncated
+ at completion, the same path can also be safely given to
+ \--import-marks.
+
+--import-marks=<file>::
+ Before processing any input, load the marks specified in
+ <file>. The input file must exist, must be readable, and
+ must use the same format as produced by \--export-marks.
++
+Any commits that have already been marked will not be exported again.
+If the backend uses a similar \--import-marks file, this allows for
+incremental bidirectional exporting of the repository by keeping the
+marks the same across runs.
+
EXAMPLES
--------
</div>\r
<h2>SYNOPSIS</h2>\r
<div class="sectionbody">\r
-<p><em>git-update-ref</em> [-m <reason>] (-d <ref> <oldvalue> | [--no-deref] <ref> <newvalue> [<oldvalue>])</p>\r
+<p><em>git-update-ref</em> [-m <reason>] (-d <ref> [<oldvalue>] | [--no-deref] <ref> <newvalue> [<oldvalue>])</p>\r
</div>\r
<h2>DESCRIPTION</h2>\r
<div class="sectionbody">\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 08-Jun-2008 01:34:21 UTC\r
+Last updated 23-Jun-2008 07:13:36 UTC\r
</div>\r
</div>\r
</body>\r
SYNOPSIS
--------
-'git-update-ref' [-m <reason>] (-d <ref>
<oldvalue> | [--no-deref] <ref> <newvalue> [<oldvalue>])
+'git-update-ref' [-m <reason>] (-d <ref>
[<oldvalue>] | [--no-deref] <ref> <newvalue> [<oldvalue>])
DESCRIPTION
-----------
frotz unspecified</tt></pre>\r
</div></div>\r
<h3>Creating an archive</h3>\r
+<h4><tt>export-ignore</tt></h4>\r
+<p>Files and directories with the attribute <tt>export-ignore</tt> won't be added to\r
+archive files.</p>\r
<h4><tt>export-subst</tt></h4>\r
<p>If the attribute <tt>export-subst</tt> is set for a file then git will expand\r
several placeholders when adding this file to an archive. The\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 08-Jun-2008 01:34:26 UTC\r
+Last updated 23-Jun-2008 07:13:37 UTC\r
</div>\r
</div>\r
</body>\r
Creating an archive
~~~~~~~~~~~~~~~~~~~
+`export-ignore`
+^^^^^^^^^^^^^^^
+
+Files and directories with the attribute `export-ignore` won't be added to
+archive files.
+
`export-subst`
^^^^^^^^^^^^^^
</div>\r
<h2>Adding a new built-in</h2>\r
<div class="sectionbody">\r
-<p>There are 4 things to do to add a bulit-in command implementation to\r
+<p>There are 4 things to do to add a built-in command implementation to\r
git:</p>\r
<ol>\r
<li>\r
<div class="content">\r
<pre><tt>{ "foo", cmd_foo, <options> },</tt></pre>\r
</div></div>\r
-<div class="literalblock">\r
-<div class="content">\r
-<pre><tt>where options is the bitwise-or of:</tt></pre>\r
-</div></div>\r
+<p>where options is the bitwise-or of:</p>\r
<dl>\r
<dt>\r
<tt>RUN_SETUP</tt>\r
feed our output to it.\r
</p>\r
</dd>\r
+<dt>\r
+<tt>NEED_WORK_TREE</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Make sure there is a work tree, i.e. the command cannot act\r
+ on bare repositories.\r
+ This makes only sense when <tt>RUN_SETUP</tt> is also set.\r
+</p>\r
+</dd>\r
</dl>\r
</li>\r
<li>\r
</li>\r
<li>\r
<p>\r
-Add an entry for <tt>git-foo</tt> to the list at the end of\r
- <tt>Documentation/cmd-list.perl</tt>.\r
+Add an entry for <tt>git-foo</tt> to <tt>command-list.txt</tt>.\r
</p>\r
</li>\r
</ol>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 08-Jun-2008 01:34:37 UTC\r
+Last updated 23-Jun-2008 07:13:38 UTC\r
</div>\r
</div>\r
</body>\r
Adding a new built-in
---------------------
-There are 4 things to do to add a bulit-in command implementation to
+There are 4 things to do to add a built-in command implementation to
git:
. Define the implementation of the built-in command `foo` with
defined in `git.c`. The entry should look like:
{ "foo", cmd_foo, <options> },
-
- where options is the bitwise-or of:
++
+where options is the bitwise-or of:
`RUN_SETUP`::
If the standard output is connected to a tty, spawn a pager and
feed our output to it.
+`NEED_WORK_TREE`::
+
+ Make sure there is a work tree, i.e. the command cannot act
+ on bare repositories.
+ This makes only sense when `RUN_SETUP` is also set.
+
. Add `builtin-foo.o` to `BUILTIN_OBJS` in `Makefile`.
Additionally, if `foo` is a new command, there are 3 more things to do:
. Write documentation in `Documentation/git-foo.txt`.
-. Add an entry for `git-foo` to the list at the end of
- `Documentation/cmd-list.perl`.
+. Add an entry for `git-foo` to `command-list.txt`.
How a built-in is called
</div>\r
<div id="preamble">\r
<div class="sectionbody">\r
-<p>Talk about <parse-options.h></p>\r
-<p>(Pierre)</p>\r
+<p>The parse-options API is used to parse and massage options in git\r
+and to provide a usage help with consistent look.</p>\r
</div>\r
</div>\r
+<h2>Basics</h2>\r
+<div class="sectionbody">\r
+<p>The argument vector <tt>argv[]</tt> may usually contain mandatory or optional\r
+<em>non-option arguments</em>, e.g. a filename or a branch, and <em>options</em>.\r
+Options are optional arguments that start with a dash and\r
+that allow to change the behavior of a command.</p>\r
+<ul>\r
+<li>\r
+<p>\r
+There are basically three types of options:\r
+ <em>boolean</em> options,\r
+ options with (mandatory) <em>arguments</em> and\r
+ options with <em>optional arguments</em>\r
+ (i.e. a boolean option that can be adjusted).\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+There are basically two forms of options:\r
+ <em>Short options</em> consist of one dash (<tt>-</tt>) and one alphanumeric\r
+ character.\r
+ <em>Long options</em> begin with two dashes (<tt>--</tt>) and some\r
+ alphanumeric characters.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Options are case-sensitive.\r
+ Please define <em>lower-case long options</em> only.\r
+</p>\r
+</li>\r
+</ul>\r
+<p>The parse-options API allows:</p>\r
+<ul>\r
+<li>\r
+<p>\r
+<em>sticked</em> and <em>separate form</em> of options with arguments.\r
+ <tt>-oArg</tt> is sticked, <tt>-o Arg</tt> is separate form.\r
+ <tt>--option=Arg</tt> is sticked, <tt>--option Arg</tt> is separate form.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Long options may be <em>abbreviated</em>, as long as the abbreviation\r
+ is unambiguous.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Short options may be bundled, e.g. <tt>-a -b</tt> can be specified as <tt>-ab</tt>.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Boolean long options can be <em>negated</em> (or <em>unset</em>) by prepending\r
+ <tt>no-</tt>, e.g. <tt>--no-abbrev</tt> instead of <tt>--abbrev</tt>.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Options and non-option arguments can clearly be separated using the <tt>--</tt>\r
+ option, e.g. <tt>-a -b --option -- --this-is-a-file</tt> indicates that\r
+ <tt>--this-is-a-file</tt> must not be processed as an option.\r
+</p>\r
+</li>\r
+</ul>\r
+</div>\r
+<h2>Steps to parse options</h2>\r
+<div class="sectionbody">\r
+<ol>\r
+<li>\r
+<p>\r
+<tt>#include "parse-options.h"</tt>\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+define a NULL-terminated\r
+ <tt>static const char * const builtin_foo_usage[]</tt> array\r
+ containing alternative usage strings\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+define <tt>builtin_foo_options</tt> array as described below\r
+ in section <em>Data Structure</em>.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+in <tt>cmd_foo(int argc, const char **argv, const char *prefix)</tt>\r
+ call\r
+</p>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><tt>argc = parse_options(argc, argv, builtin_foo_options, builtin_foo_usage, flags);</tt></pre>\r
+</div></div>\r
+<p><tt>parse_options()</tt> will filter out the processed options of <tt>argv[]</tt> and leave the\r
+non-option arguments in <tt>argv[]</tt>.\r
+<tt>argc</tt> is updated appropriately because of the assignment.</p>\r
+<p>Flags are the bitwise-or of:</p>\r
+<dl>\r
+<dt>\r
+<tt>PARSE_OPT_KEEP_DASHDASH</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Keep the <tt>--</tt> that usually separates options from\r
+ non-option arguments.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>PARSE_OPT_STOP_AT_NON_OPTION</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Usually the whole argument vector is massaged and reordered.\r
+ Using this flag, processing is stopped at the first non-option\r
+ argument.\r
+</p>\r
+</dd>\r
+</dl>\r
+</li>\r
+</ol>\r
+</div>\r
+<h2>Data Structure</h2>\r
+<div class="sectionbody">\r
+<p>The main data structure is an array of the <tt>option</tt> struct,\r
+say <tt>static struct option builtin_add_options[]</tt>.\r
+There are some macros to easily define options:</p>\r
+<dl>\r
+<dt>\r
+<tt>OPT__ABBREV(&int_var)</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Add <tt>--abbrev[=<n>]</tt>.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>OPT__DRY_RUN(&int_var)</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Add <tt>-n, --dry-run</tt>.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>OPT__QUIET(&int_var)</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Add <tt>-q, --quiet</tt>.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>OPT__VERBOSE(&int_var)</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Add <tt>-v, --verbose</tt>.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>OPT_GROUP(description)</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Start an option group. <tt>description</tt> is a short string that\r
+ describes the group or an empty string.\r
+ Start the description with an upper-case letter.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>OPT_BOOLEAN(short, long, &int_var, description)</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Introduce a boolean option.\r
+ <tt>int_var</tt> is incremented on each use.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>OPT_BIT(short, long, &int_var, description, mask)</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Introduce a boolean option.\r
+ If used, <tt>int_var</tt> is bitwise-ored with <tt>mask</tt>.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>OPT_SET_INT(short, long, &int_var, description, integer)</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Introduce a boolean option.\r
+ If used, set <tt>int_var</tt> to <tt>integer</tt>.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>OPT_SET_PTR(short, long, &ptr_var, description, ptr)</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Introduce a boolean option.\r
+ If used, set <tt>ptr_var</tt> to <tt>ptr</tt>.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>OPT_STRING(short, long, &str_var, arg_str, description)</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Introduce an option with string argument.\r
+ The string argument is put into <tt>str_var</tt>.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>OPT_INTEGER(short, long, &int_var, description)</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Introduce an option with integer argument.\r
+ The integer is put into <tt>int_var</tt>.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>OPT_DATE(short, long, &int_var, description)</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Introduce an option with date argument, see <tt>approxidate()</tt>.\r
+ The timestamp is put into <tt>int_var</tt>.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Introduce an option with argument.\r
+ The argument will be fed into the function given by <tt>func_ptr</tt>\r
+ and the result will be put into <tt>var</tt>.\r
+ See <em>Option Callbacks</em> below for a more elaborate description.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>OPT_ARGUMENT(long, description)</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Introduce a long-option argument that will be kept in <tt>argv[]</tt>.\r
+</p>\r
+</dd>\r
+</dl>\r
+<p>The last element of the array must be <tt>OPT_END()</tt>.</p>\r
+<p>If not stated otherwise, interpret the arguments as follows:</p>\r
+<ul>\r
+<li>\r
+<p>\r
+<tt>short</tt> is a character for the short option\r
+ (e.g. <tt>'e'</tt> for <tt>-e</tt>, use <tt>0</tt> to omit),\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>long</tt> is a string for the long option\r
+ (e.g. <tt>"example"</tt> for <tt>--example</tt>, use <tt>NULL</tt> to omit),\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>int_var</tt> is an integer variable,\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>str_var</tt> is a string variable (<tt>char *</tt>),\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>arg_str</tt> is the string that is shown as argument\r
+ (e.g. <tt>"branch"</tt> will result in <tt><branch></tt>).\r
+ If set to <tt>NULL</tt>, three dots (<tt>…</tt>) will be displayed.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>description</tt> is a short string to describe the effect of the option.\r
+ It shall begin with a lower-case letter and a full stop (<tt>.</tt>) shall be\r
+ omitted at the end.\r
+</p>\r
+</li>\r
+</ul>\r
+</div>\r
+<h2>Option Callbacks</h2>\r
+<div class="sectionbody">\r
+<p>The function must be defined in this form:</p>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><tt>int func(const struct option *opt, const char *arg, int unset)</tt></pre>\r
+</div></div>\r
+<p>The callback mechanism is as follows:</p>\r
+<ul>\r
+<li>\r
+<p>\r
+Inside <tt>funct</tt>, the only interesting member of the structure\r
+ given by <tt>opt</tt> is the void pointer <tt>opt->value</tt>.\r
+ <tt>*opt->value</tt> will be the value that is saved into <tt>var</tt>, if you\r
+ use <tt>OPT_CALLBACK()</tt>.\r
+ For example, do <tt>*(unsigned long *)opt->value = 42;</tt> to get 42\r
+ into an <tt>unsigned long</tt> variable.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Return value <tt>0</tt> indicates success and non-zero return\r
+ value will invoke <tt>usage_with_options()</tt> and, thus, die.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+If the user negates the option, <tt>arg</tt> is <tt>NULL</tt> and <tt>unset</tt> is 1.\r
+</p>\r
+</li>\r
+</ul>\r
+</div>\r
+<h2>Sophisticated option parsing</h2>\r
+<div class="sectionbody">\r
+<p>If you need, for example, option callbacks with optional arguments\r
+or without arguments at all, or if you need other special cases,\r
+that are not handled by the macros above, you need to specify the\r
+members of the <tt>option</tt> structure manually.</p>\r
+<p>This is not covered in this document, but well documented\r
+in <tt>parse-options.h</tt> itself.</p>\r
+</div>\r
+<h2>Examples</h2>\r
+<div class="sectionbody">\r
+<p>See <tt>test-parse-options.c</tt> and\r
+<tt>builtin-add.c</tt>,\r
+<tt>builtin-clone.c</tt>,\r
+<tt>builtin-commit.c</tt>,\r
+<tt>builtin-fetch.c</tt>,\r
+<tt>builtin-fsck.c</tt>,\r
+<tt>builtin-rm.c</tt>\r
+for real-world examples.</p>\r
+</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 08-Jun-2008 01:34:45 UTC\r
+Last updated 23-Jun-2008 07:13:38 UTC\r
</div>\r
</div>\r
</body>\r
parse-options API
=================
-Talk about <parse-options.h>
+The parse-options API is used to parse and massage options in git
+and to provide a usage help with consistent look.
-(Pierre)
+Basics
+------
+
+The argument vector `argv[]` may usually contain mandatory or optional
+'non-option arguments', e.g. a filename or a branch, and 'options'.
+Options are optional arguments that start with a dash and
+that allow to change the behavior of a command.
+
+* There are basically three types of options:
+ 'boolean' options,
+ options with (mandatory) 'arguments' and
+ options with 'optional arguments'
+ (i.e. a boolean option that can be adjusted).
+
+* There are basically two forms of options:
+ 'Short options' consist of one dash (`-`) and one alphanumeric
+ character.
+ 'Long options' begin with two dashes (`\--`) and some
+ alphanumeric characters.
+
+* Options are case-sensitive.
+ Please define 'lower-case long options' only.
+
+The parse-options API allows:
+
+* 'sticked' and 'separate form' of options with arguments.
+ `-oArg` is sticked, `-o Arg` is separate form.
+ `\--option=Arg` is sticked, `\--option Arg` is separate form.
+
+* Long options may be 'abbreviated', as long as the abbreviation
+ is unambiguous.
+
+* Short options may be bundled, e.g. `-a -b` can be specified as `-ab`.
+
+* Boolean long options can be 'negated' (or 'unset') by prepending
+ `no-`, e.g. `\--no-abbrev` instead of `\--abbrev`.
+
+* Options and non-option arguments can clearly be separated using the `\--`
+ option, e.g. `-a -b \--option \-- \--this-is-a-file` indicates that
+ `\--this-is-a-file` must not be processed as an option.
+
+Steps to parse options
+----------------------
+
+. `#include "parse-options.h"`
+
+. define a NULL-terminated
+ `static const char * const builtin_foo_usage[]` array
+ containing alternative usage strings
+
+. define `builtin_foo_options` array as described below
+ in section 'Data Structure'.
+
+. in `cmd_foo(int argc, const char **argv, const char *prefix)`
+ call
+
+ argc = parse_options(argc, argv, builtin_foo_options, builtin_foo_usage, flags);
++
+`parse_options()` will filter out the processed options of `argv[]` and leave the
+non-option arguments in `argv[]`.
+`argc` is updated appropriately because of the assignment.
++
+Flags are the bitwise-or of:
+
+`PARSE_OPT_KEEP_DASHDASH`::
+ Keep the `\--` that usually separates options from
+ non-option arguments.
+
+`PARSE_OPT_STOP_AT_NON_OPTION`::
+ Usually the whole argument vector is massaged and reordered.
+ Using this flag, processing is stopped at the first non-option
+ argument.
+
+Data Structure
+--------------
+
+The main data structure is an array of the `option` struct,
+say `static struct option builtin_add_options[]`.
+There are some macros to easily define options:
+
+`OPT__ABBREV(&int_var)`::
+ Add `\--abbrev[=<n>]`.
+
+`OPT__DRY_RUN(&int_var)`::
+ Add `-n, \--dry-run`.
+
+`OPT__QUIET(&int_var)`::
+ Add `-q, \--quiet`.
+
+`OPT__VERBOSE(&int_var)`::
+ Add `-v, \--verbose`.
+
+`OPT_GROUP(description)`::
+ Start an option group. `description` is a short string that
+ describes the group or an empty string.
+ Start the description with an upper-case letter.
+
+`OPT_BOOLEAN(short, long, &int_var, description)`::
+ Introduce a boolean option.
+ `int_var` is incremented on each use.
+
+`OPT_BIT(short, long, &int_var, description, mask)`::
+ Introduce a boolean option.
+ If used, `int_var` is bitwise-ored with `mask`.
+
+`OPT_SET_INT(short, long, &int_var, description, integer)`::
+ Introduce a boolean option.
+ If used, set `int_var` to `integer`.
+
+`OPT_SET_PTR(short, long, &ptr_var, description, ptr)`::
+ Introduce a boolean option.
+ If used, set `ptr_var` to `ptr`.
+
+`OPT_STRING(short, long, &str_var, arg_str, description)`::
+ Introduce an option with string argument.
+ The string argument is put into `str_var`.
+
+`OPT_INTEGER(short, long, &int_var, description)`::
+ Introduce an option with integer argument.
+ The integer is put into `int_var`.
+
+`OPT_DATE(short, long, &int_var, description)`::
+ Introduce an option with date argument, see `approxidate()`.
+ The timestamp is put into `int_var`.
+
+`OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`::
+ Introduce an option with argument.
+ The argument will be fed into the function given by `func_ptr`
+ and the result will be put into `var`.
+ See 'Option Callbacks' below for a more elaborate description.
+
+`OPT_ARGUMENT(long, description)`::
+ Introduce a long-option argument that will be kept in `argv[]`.
+
+
+The last element of the array must be `OPT_END()`.
+
+If not stated otherwise, interpret the arguments as follows:
+
+* `short` is a character for the short option
+ (e.g. `\'e\'` for `-e`, use `0` to omit),
+
+* `long` is a string for the long option
+ (e.g. `"example"` for `\--example`, use `NULL` to omit),
+
+* `int_var` is an integer variable,
+
+* `str_var` is a string variable (`char *`),
+
+* `arg_str` is the string that is shown as argument
+ (e.g. `"branch"` will result in `<branch>`).
+ If set to `NULL`, three dots (`...`) will be displayed.
+
+* `description` is a short string to describe the effect of the option.
+ It shall begin with a lower-case letter and a full stop (`.`) shall be
+ omitted at the end.
+
+Option Callbacks
+----------------
+
+The function must be defined in this form:
+
+ int func(const struct option *opt, const char *arg, int unset)
+
+The callback mechanism is as follows:
+
+* Inside `funct`, the only interesting member of the structure
+ given by `opt` is the void pointer `opt->value`.
+ `\*opt->value` will be the value that is saved into `var`, if you
+ use `OPT_CALLBACK()`.
+ For example, do `*(unsigned long *)opt->value = 42;` to get 42
+ into an `unsigned long` variable.
+
+* Return value `0` indicates success and non-zero return
+ value will invoke `usage_with_options()` and, thus, die.
+
+* If the user negates the option, `arg` is `NULL` and `unset` is 1.
+
+Sophisticated option parsing
+----------------------------
+
+If you need, for example, option callbacks with optional arguments
+or without arguments at all, or if you need other special cases,
+that are not handled by the macros above, you need to specify the
+members of the `option` structure manually.
+
+This is not covered in this document, but well documented
+in `parse-options.h` itself.
+
+Examples
+--------
+
+See `test-parse-options.c` and
+`builtin-add.c`,
+`builtin-clone.c`,
+`builtin-commit.c`,
+`builtin-fetch.c`,
+`builtin-fsck.c`,
+`builtin-rm.c`
+for real-world examples.
projects / git.git / commitdiff