Motivation

A common use case for command line tools, e.g. git, is to have multiple subcommands, e.g. git fetch or git push. Each subcommand has its own set of options and its own help page. This HowTo explains how this can be done with the sharg::parser and serves as a copy'n'paste source. If you are new to Sharg, we recommend to do the basic parser tutorial before you read further.

A subcommand parser

In order to keep parsing with subcommands straightforward and simple, the sharg::parser provides an advanced interface that internally takes care of the correct input parsing.

You simply need to specify the names of the subcommands when constructing your top-level parser:

sharg::parser top_level_parser{"mygit", argc, argv, sharg::update_notifications::on, {"push", "pull"}};

Attention: You can still add flags to your top-level parser if needed but no (positional) options. This avoids ambiguous parsing (e.g. subcommand fasta given file extension fasta ./myfasta_parser --filext fasta fasta ...).

After calling sharg::parser::parse() on your top-level parser, you can then access the sub-parser via the function sharg::parser::get_sub_parser():

// hold a reference to the sub_parser

sharg::parser & sub_parser = top_level_parser.get_sub_parser();

The sub-parser's sharg::parser::info::app_name will be set to the user chosen sub command. For example, if the user calls

max$ ./mygit push -h

then the sub-parser will be named mygit-push and will be instantiated with all arguments followed by the keyword push which in this case triggers printing the help page (-h).

That's it. Here is a full example of a subcommand parser you can try and adjust to your needs:

// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
 
#include <sharg/all.hpp>
 
// =====================================================================================================================
// pull
// =====================================================================================================================
 
struct pull_arguments
{
    std::string repository{};
    std::string branch{};
    bool progress{false};
};
 
int run_git_pull(sharg::parser & parser)
{
    pull_arguments args{};
 
    parser.add_positional_option(args.repository, sharg::config{.description = "The repository name to pull from."});
    parser.add_positional_option(args.branch, sharg::config{.description = "The branch name to pull from."});
 
    try
    {
        parser.parse();
    }
    catch (sharg::parser_error const & ext)
    {
        std::cerr << "[Error git pull] " << ext.what() << "\n";
        return -1;
    }
 
    std::cerr << "Git pull with repository " << args.repository << " and branch " << args.branch << '\n';
 
    return 0;
}
 
// =====================================================================================================================
// push
// =====================================================================================================================
 
struct push_arguments
{
    std::string repository{};
    std::vector<std::string> branches{};
    bool push_all{false};
};
 
int run_git_push(sharg::parser & parser)
{
    push_arguments args{};
 
    parser.add_positional_option(args.repository, sharg::config{.description = "The repository name to push to."});
    parser.add_positional_option(args.branches, sharg::config{.description = "The branch names to push."});
 
    try
    {
        parser.parse();
    }
    catch (sharg::parser_error const & ext)
    {
        std::cerr << "[Error git push] " << ext.what() << "\n";
        return -1;
    }
 
    std::cerr << "Git push with repository " << args.repository << " and branches ";
    for (auto && branch : args.branches)
        std::cerr << branch << ' ';
    std::cerr << '\n';
 
    return 0;
}
 
// =====================================================================================================================
// main
// =====================================================================================================================
 
int main(int argc, char const ** argv)
{
    sharg::parser top_level_parser{"mygit", argc, argv, sharg::update_notifications::on, {"push", "pull"}};
 
 
    // Add information and flags, but no (positional) options to your top-level parser.
    // Because of ambiguity, we do not allow any (positional) options for the top-level parser.
    top_level_parser.info.description.push_back("You can push or pull from a remote repository.");
    bool flag{false};
    top_level_parser.add_flag(flag, sharg::config{.short_id = 'f', .long_id = "flag", .description = "some flag"});
 
    try
    {
        top_level_parser.parse(); // trigger command line parsing
    }
    catch (sharg::parser_error const & ext) // catch user errors
    {
        std::cerr << "[Error] " << ext.what() << "\n"; // customise your error message
        return -1;
    }
 
    // hold a reference to the sub_parser
    sharg::parser & sub_parser = top_level_parser.get_sub_parser();
 
    std::cout << "Proceed to sub parser.\n";
 
    if (sub_parser.info.app_name == std::string_view{"mygit-pull"})
        return run_git_pull(sub_parser);
    else if (sub_parser.info.app_name == std::string_view{"mygit-push"})
        return run_git_push(sub_parser);
    else
        std::cout << "Unhandled subparser named " << sub_parser.info.app_name << '\n';
    // Note: Arriving in this else branch means you did not handle all sub_parsers in the if branches above.
 
    return 0;
}

Recursive subcommands

If you want to have subcommands with subcommands, you can add subcommands to the sub-parser with sharg::parser::add_subcommands():

// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
 
#include <sharg/all.hpp>
 
void run(std::vector<std::string> const & arguments)
{
    sharg::parser git_parser{"git", arguments, sharg::update_notifications::off, {"pull", "push"}};
    git_parser.add_subcommands({"remote"});
    git_parser.parse();
 
    sharg::parser & sub_parser = git_parser.get_sub_parser();
 
    if (sub_parser.info.app_name == std::string_view{"git-pull"})
    {
        auto & pull_parser = sub_parser;
        std::string repository{};
        pull_parser.add_positional_option(repository, sharg::config{});
        pull_parser.parse();
    }
    else if (sub_parser.info.app_name == std::string_view{"git-push"})
    {
        auto & push_parser = sub_parser;
        std::string repository{};
        push_parser.add_positional_option(repository, sharg::config{});
        push_parser.parse();
    }
    else if (sub_parser.info.app_name == std::string_view{"git-remote"})
    {
        auto & remote_parser = sub_parser;
        remote_parser.add_subcommands({"set-url", "show"});
        remote_parser.parse();
 
        sharg::parser & recursive_sub_parser = remote_parser.get_sub_parser();
 
        if (recursive_sub_parser.info.app_name == std::string_view{"git-remote-set-url"})
        {
            auto & set_url_parser = recursive_sub_parser;
            std::string repository{};
            set_url_parser.add_positional_option(repository, sharg::config{});
            set_url_parser.parse();
        }
        else if (recursive_sub_parser.info.app_name == std::string_view{"git-remote-show"})
        {
            auto & show_parser = recursive_sub_parser;
            show_parser.parse();
        }
    }
}
 
int main(int argc, char ** argv)
{
    try
    {
        run({argv, argv + argc});
    }
    catch (sharg::parser_error const & ext)
    {
        std::cerr << "[Error] " << ext.what() << '\n';
        std::exit(-1);
    }
 
    return 0;
}

Difficulty	Easy
Duration	15 min
Prerequisite tutorials	Parsing command line arguments with Sharg
Recommended reading

Table of Contents

Motivation

A subcommand parser

Recursive subcommands