# Subcommands and the App

Subcommands are keyword that invoke a new set of options and features. For example, the `git`
command has a long series of subcommands, like `add` and `commit`. Each can have its own options
and implementations. This chapter will focus on implementations that are contained in the same
C++ application, though the system git uses to extend the main command by calling other commands
in separate executables is supported too; that's called "Prefix commands" and is included at the
end of this chapter.


## The parent App

We'll start by discussing the parent `App`. You've already used it quite a bit, to create
options and set option defaults. There are several other things you can do with an `App`, however.

You are given a lot of control the help output. You can set a footer with `app.footer("My Footer")`.
You can replace the default help print when a `ParseError` is thrown with `app.set_failure_message(CLI::FailureMessage::help)`.
The default is `CLI:::FailureMessage::simple`, and you can easily define a new one. Just make a (lambda) function that takes an App pointer
and a reference to an error code (even if you don't use them), and returns a string.


## Adding a subcommand

Subcommands can be added just like an option:

```cpp
CLI::App* sub = app.add_subcommand("sub", "This is a subcommand");
```

The subcommand should have a name as the first argument, and a little description for the
second argument. A pointer to the internally stored subcommand is provided; you usually will
be capturing that pointer and using it later (though you can use callbacks if you prefer). As
always, feel free to use `auto sub = ...` instead of naming the type.

You can check to see if the subcommand was received on the command line several ways:

```cpp
if(*sub) ...
if(sub->parsed()) ...
if(app.got_subcommand(sub)) ...
if(app.got_subcommand("sub")) ...
```

You can also get a list of subcommands with `get_subcommands()`, and they will be in parsing order.

There are a lot of options that you can set on a subcommand; in fact,
subcommands have exactly the same options as your main app, since they are actually
the same class of object (as you may have guessed from the type above). This has the
pleasant side affect of making subcommands infinitely nestable.

## Required subcommands

Each App has controls to set the number of subcommands you expect. This is controlled by:

```cpp
app.require_subcommand(/* min */ 0, /* max */ 1);
```
If you set the max to 0, CLI11 will allow an unlimited number of subcommands. After the (non-unlimited) maximum
is reached, CLI11 will stop trying to match subcommands. So the if you pass "`one two`" to a command, and both `one`
and `two` are subcommands, it will depend on the maximum number as to whether the "`two`" is a subcommand or an argument to the
"`one`" subcommand.

As a shortcut, you can also call the `require_subcommand` method with one argument; that will be the fixed number of subcommands if positive, it
will be the maximum number if negative. Calling it without an argument will set the required subcommands to 1 or more.

The maximum number of subcommands is inherited by subcommands. This allows you to set the maximum to 1 once at the beginning on the parent app if you only want single subcommands throughout your app. You should keep this in mind, if you are dealing with lots of nested subcommands.

## Using callbacks

You've already seen how to check to see what subcommands were given. It's often much easier, however, to just define the code you want to run when you are making your parser, and not run a bunch of code after `CLI11_PARSE` to analyse the state (Procedural! Yuck!). You can do that with lambda functions. A `std::function<void()>` callback `.callback()` is provided, and CLI11 ensures that all options are prepared and usable by reference capture before entering the callback. An
example is shown below in the `geet` program.

## Inheritance of defaults

The following values are inherited when you add a new subcommand. This happens at the point the subcommand is created:

* The name and description for the help flag
* The footer
* The failure message printer function
* Option defaults
* Allow extras
* Prefix command
* Ignore case
* Ignore underscore
* Allow Windows style options
* Fallthrough
* Group name
* Max required subcommands

## Special modes

There are several special modes for Apps and Subcommands.

### Allow extras

Normally CLI11 throws an error if you don't match all items given on the command line. However, you can enable `allow_extras()`
to instead store the extra values in `.remaining()`. You can get all remaining options including those in contained subcommands recursively in the original order with `.remaining(true)`.
`.remaining_size()` is also provided; this counts the size but ignores the `--` special separator if present.

### Fallthrough

Fallthrough allows an option that does not match in a subcommand to "fall through" to the parent command; if that parent
allows that option, it matches there instead. This was added to allow CLI11 to represent models:

```term
gitbook:code $ ./my_program my_model_1 --model_flag --shared_flag
```

Here, `--shared_flag` was set on the main app, and on the command line it "falls through" `my_model_1` to match on the main app.

### Prefix command

This is a special mode that allows "prefix" commands, where the parsing completely stops when it gets to an unknown option. Further unknown options are ignored, even if they could match. Git is the traditional example for prefix commands; if you run git with an unknown subcommand, like "`git thing`", it then calls another command called "`git-thing`" with the remaining options intact.

