From 4224f999337f29b477b197e893f07c5e24917b11 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Mon, 23 Jun 2008 07:14:08 +0000 Subject: [PATCH] Autogenerated HTML docs for v1.5.6-49-g112db --- config.txt | 19 ++ git-commit.html | 36 +++- git-commit.txt | 25 ++- git-config.html | 36 +++- git-fast-export.html | 31 ++- git-fast-export.txt | 20 ++ git-update-ref.html | 4 +- git-update-ref.txt | 2 +- gitattributes.html | 5 +- gitattributes.txt | 6 + technical/api-builtin.html | 22 +- technical/api-builtin.txt | 15 +- technical/api-parse-options.html | 355 ++++++++++++++++++++++++++++++- technical/api-parse-options.txt | 204 +++++++++++++++++- 14 files changed, 739 insertions(+), 41 deletions(-) diff --git a/config.txt b/config.txt index 5331b450e..1e09a57c8 100644 --- a/config.txt +++ b/config.txt @@ -1013,6 +1013,25 @@ status.relativePaths:: 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 diff --git a/git-commit.html b/git-commit.html index 59f8050d0..96224bce7 100644 --- a/git-commit.html +++ b/git-commit.html @@ -273,7 +273,7 @@ git-commit(1) Manual Page

SYNOPSIS

-
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>…]
@@ -537,19 +537,37 @@ that, you can recover from it with git-reset(1).

--u +-u[<mode>]
---untracked-files +--untracked-files[=<mode>]

- 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. + 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 git-config(1) for configuration variable +used to change the default for when the option is not +specified.

-v @@ -795,7 +813,7 @@ Junio C Hamano <junkio@cox.net>

diff --git a/git-commit.txt b/git-commit.txt index 7e8b4ff72..d0fe192fb 100644 --- a/git-commit.txt +++ b/git-commit.txt @@ -8,7 +8,7 @@ git-commit - Record changes to the repository SYNOPSIS -------- [verse] -'git-commit' [-a | --interactive] [-s] [-v] [-u] [--amend] +'git-commit' [-a | --interactive] [-s] [-v] [-u] [--amend] [(-c | -C) ] [-F | -m ] [--allow-empty] [--no-verify] [-e] [--author=] [--cleanup=] [--] [[-i | -o ]...] @@ -162,13 +162,22 @@ but can be used to amend a merge commit. 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[]:: +--untracked-files[=]:: + 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:: diff --git a/git-config.html b/git-config.html index d8355c171..ed6215c55 100644 --- a/git-config.html +++ b/git-config.html @@ -2451,6 +2451,40 @@ status.relativePaths

+status.showUntrackedFiles +
+
+

+ By default, git-status(1) and 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 git-status(1) and git-commit(1).

+
+
tar.umask
@@ -2601,7 +2635,7 @@ web.browser
diff --git a/git-fast-export.html b/git-fast-export.html index 805885639..ec84222c8 100644 --- a/git-fast-export.html +++ b/git-fast-export.html @@ -308,6 +308,35 @@ when encountering a signed tag. With strip, the tags will be made 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

@@ -351,7 +380,7 @@ a tag referencing a tree instead of a commit.

diff --git a/git-fast-export.txt b/git-fast-export.txt index 332346cc5..277a547a0 100644 --- a/git-fast-export.txt +++ b/git-fast-export.txt @@ -36,6 +36,26 @@ when encountering a signed tag. With 'strip', the tags will be made unsigned, with 'verbatim', they will be silently exported and with 'warn', they will be exported, but you will see a warning. +--export-marks=:: + Dumps the internal marks table to 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 is only opened and truncated + at completion, the same path can also be safely given to + \--import-marks. + +--import-marks=:: + Before processing any input, load the marks specified in + . 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 -------- diff --git a/git-update-ref.html b/git-update-ref.html index 10a23b2e4..4cab62f65 100644 --- a/git-update-ref.html +++ b/git-update-ref.html @@ -272,7 +272,7 @@ git-update-ref(1) Manual Page

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

@@ -360,7 +360,7 @@ or does not have committer information available.

diff --git a/git-update-ref.txt b/git-update-ref.txt index 7f7e3d197..bae2c8b7e 100644 --- a/git-update-ref.txt +++ b/git-update-ref.txt @@ -7,7 +7,7 @@ git-update-ref - Update the object name stored in a ref safely SYNOPSIS -------- -'git-update-ref' [-m ] (-d | [--no-deref] []) +'git-update-ref' [-m ] (-d [] | [--no-deref] []) DESCRIPTION ----------- diff --git a/gitattributes.html b/gitattributes.html index 992860d0e..8268e27d8 100644 --- a/gitattributes.html +++ b/gitattributes.html @@ -806,6 +806,9 @@ merge set to string value "filfre" frotz unspecified

Creating an archive

+

export-ignore

+

Files and directories with the attribute export-ignore won't be added to +archive files.

export-subst

If the attribute export-subst is set for a file then git will expand several placeholders when adding this file to an archive. The @@ -823,7 +826,7 @@ commit hash.

diff --git a/gitattributes.txt b/gitattributes.txt index 471754eb1..6e67990f6 100644 --- a/gitattributes.txt +++ b/gitattributes.txt @@ -502,6 +502,12 @@ frotz unspecified Creating an archive ~~~~~~~~~~~~~~~~~~~ +`export-ignore` +^^^^^^^^^^^^^^^ + +Files and directories with the attribute `export-ignore` won't be added to +archive files. + `export-subst` ^^^^^^^^^^^^^^ diff --git a/technical/api-builtin.html b/technical/api-builtin.html index f75dcf443..db0584b30 100644 --- a/technical/api-builtin.html +++ b/technical/api-builtin.html @@ -263,7 +263,7 @@ div.exampleblock-content {

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:

  1. @@ -290,10 +290,7 @@ Add the command to commands[] table in handle_internal_command() 
    { "foo", cmd_foo, <options> },
-
-
-
where options is the bitwise-or of:
-
+

where options is the bitwise-or of:

RUN_SETUP @@ -315,6 +312,16 @@ Add the command to commands[] table in handle_internal_command() +
+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. +

+
  • @@ -337,8 +344,7 @@ 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.

    • @@ -359,7 +365,7 @@ command.

    diff --git a/technical/api-builtin.txt b/technical/api-builtin.txt index 52cdb4c52..7ede1e64e 100644 --- a/technical/api-builtin.txt +++ b/technical/api-builtin.txt @@ -4,7 +4,7 @@ builtin API 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 @@ -18,8 +18,8 @@ git: defined in `git.c`. The entry should look like: { "foo", cmd_foo, }, - - where options is the bitwise-or of: ++ +where options is the bitwise-or of: `RUN_SETUP`:: @@ -33,6 +33,12 @@ git: 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: @@ -41,8 +47,7 @@ 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 diff --git a/technical/api-parse-options.html b/technical/api-parse-options.html index 07e3352b5..d075c0542 100644 --- a/technical/api-parse-options.html +++ b/technical/api-parse-options.html @@ -263,13 +263,362 @@ div.exampleblock-content {
    -

    Talk about <parse-options.h>

    -

    (Pierre)

    +

    The parse-options API is used to parse and massage options in git +and to provide a usage help with consistent look.

    +

    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

    +
    +
      +
    1. +

      +#include "parse-options.h" +

      +
      2. +
    2. +

      +define a NULL-terminated + static const char * const builtin_foo_usage[] array + containing alternative usage strings +

      +
      3. +
    3. +

      +define builtin_foo_options array as described below + in section Data Structure. +

      +
      4. +
    4. +

      +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. +

      +
      +
      +
      5. +
    +
    +

    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.

    +
    diff --git a/technical/api-parse-options.txt b/technical/api-parse-options.txt index b7cda94f5..539863b1f 100644 --- a/technical/api-parse-options.txt +++ b/technical/api-parse-options.txt @@ -1,6 +1,206 @@ parse-options API ================= -Talk about +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[=]`. + +`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 ``). + 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. -- 2.26.2