New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve --help output #236

Merged
merged 5 commits into from Mar 6, 2018

Conversation

Projects
None yet
2 participants
@latk
Member

latk commented Mar 6, 2018

I found the --help output hard to read, so I sorted the flags into thematic groups, and edited the help messages for clarity based on my current understanding of them.

The groups are:

  • general options,
  • Output Options,
  • Filter Options, and
  • GCOV Options.

Based on my new-found understanding of these options, I made a few other changes:

  • allow multiple --gcov-filters. Previously this was the only filter that could only be used once, which needlessly complicated the code.

  • extract the common report sorting functions for text and HTML output. These are controlled by the --branches (text only), --sort-uncovered, and --sort-percentage options.

  • mention the search paths in the usage. After parsing the options, any remaining arguments are used as search paths for the data files. This was previously entirely undocumented. However, optparse only supports documentation for --options, so proper --help docs will have to wait until we move option parsing to argparse (which will be soon-ish, as I've found that arparse has been backported to all our supported Python versions).

Here is the current gcovr --help output:

Usage: gcovr [options] [search_paths...]

A utility to run gcov and summarize the coverage in simple reports.

Options:
  -h, --help            Show this help message, then exit.
  --version             Print the version number, then exit.
  -v, --verbose         Print progress messages. Please include this output in
                        bug reports.
  -r ROOT, --root=ROOT  The root directory of your source files. Defaults to
                        '.', the current directory. File names are reported
                        relative to this root. The --root is the default
                        --filter.
  --fail-under-line=MIN
                        Exit with a status of 2 if the total line coverage is
                        less than MIN. Can be ORed with exit status of '--
                        fail-under-branch' option.
  --fail-under-branch=MIN
                        Exit with a status of 4 if the total branch coverage
                        is less than MIN. Can be ORed with exit status of '--
                        fail-under-line' option.

  Output Options:
    Gcovr prints a text report by default, but can switch to XML or HTML.

    -o OUTPUT, --output=OUTPUT
                        Print output to this filename. Defaults to stdout.
                        Required for --html-details.
    -b, --branches      Report the branch coverage instead of the line
                        coverage. For text report only.
    -u, --sort-uncovered
                        Sort entries by increasing number of uncovered lines.
                        For text and HTML report.
    -p, --sort-percentage
                        Sort entries by increasing percentage of uncovered
                        lines. For text and HTML report.
    -x, --xml           Generate a Cobertura XML report.
    --xml-pretty        Pretty-print the XML report. Implies --xml. Default:
                        False.
    --html              Generate a HTML report.
    --html-details      Add annotated source code reports to the HTML report.
                        Requires --output as a basename for the reports.
                        Implies --html.
    --html-absolute-paths
                        Use absolute paths to link the --html-details reports.
                        Defaults to relative links.
    --html-encoding=HTML_ENCODING
                        Override the declared HTML report encoding. Defaults
                        to UTF-8. May be necessary for unusual source file
                        encodings. Encoding support is likely to change in the
                        future.
    -s, --print-summary
                        Print a small report to stdout with line & branch
                        percentage coverage. This is in addition to other
                        reports. Default: False.

  Filter Options:
    Filters decide which files are included in the report. Any filter must
    match, and no exclude filter must match. A filter is a regular
    expression that matches a path. On Windows, the filter must match a
    relative path.

    -f FILTER, --filter=FILTER
                        Keep only source files that match this filter. Can be
                        specified multiple times. If no filters are provided,
                        defaults to --root.
    -e EXCLUDE, --exclude=EXCLUDE
                        Exclude source files that match this filter. Can be
                        specified multiple times.
    --gcov-filter=GCOV_FILTER
                        Keep only gcov data files that match this filter. Can
                        be specified multiple times.
    --gcov-exclude=GCOV_EXCLUDE
                        Exclude gcov data files that match this filter. Can be
                        specified multiple times.
    --exclude-directories=EXCLUDE_DIRS
                        Exclude directories that match this regex while
                        searching raw coverage files. Can be specified
                        multiple times.

  GCOV Options:
    The 'gcov' tool turns raw coverage files (*.gcda and *.gcno) into
    *.gcov files that are then processed by gcovr. The gcno files are
    generated by the compiler. The gcda files are generated when the
    instrumented program is executed.

    --gcov-executable=GCOV_CMD
                        Use a particular gcov executable. Must match the
                        compiler you are using, e.g. 'llvm-cov gcov' for
                        Clang. Can include additional arguments. Defaults to
                        the GCOV environment variable, or 'gcov': 'gcov'.
    --exclude-unreachable-branches
                        Exclude branch coverage with LCOV/GCOV exclude
                        markers. Additionally, exclude branch coverage from
                        lines without useful source code (often, compiler-
                        generated "dead" code). Default: False.
    -g, --use-gcov-files
                        Use existing gcov files for analysis. Default: False.
    --gcov-ignore-parse-errors
                        Skip lines with parse errors in GCOV files instead of
                        exiting with an error. A report will be shown on
                        stderr. Default: False.
    --object-directory=OBJDIR
                        Override normal working directory detection. Gcovr
                        needs to identify the path between gcda files and the
                        directory where the compiler was originally run.
                        Normally, gcovr can guess correctly. This option
                        specifies either the path from gcc to the gcda file
                        (i.e. gcc's '-o' option), or the path from the gcda
                        file to gcc's working directory.
    -k, --keep          Keep gcov files after processing. This applies both to
                        files that were generated by gcovr, or were supplied
                        via the --use-gcov-files option. Default: False.
    -d, --delete        Delete gcda files after processing. Default: False.

See <http://gcovr.com/> for the full manual.

latk added some commits Mar 4, 2018

group options for better --help output
The list of possible options is rather lengthy. This commit divides the
list into sections, such as

  - general options,
  - Output Options,
  - Filter Options, and
  - GCOV Options.
Revise --help messages for options
The help messages were edited towards a common style. Option groups were
given general information so that the options can be more compact. The
info about each option was updated with my current understanding of
their behaviour, and clarified where appropriate.
stop special-casing --gcov-filter
Previously, this was the only filter type that could not be specified
multiple times.
clarify search path options
This was previously an entirely undocumented feature, but it's quite
important. Optparse is unable to include docs for positional arguments
in the --help message, so that will have to wait until argparse can be
used.
@codecov

This comment has been minimized.

codecov bot commented Mar 6, 2018

Codecov Report

Merging #236 into master will decrease coverage by 0.13%.
The diff coverage is 74.19%.

Impacted file tree graph

@@            Coverage Diff             @@
##           master     #236      +/-   ##
==========================================
- Coverage    87.5%   87.37%   -0.14%     
==========================================
  Files          12       12              
  Lines        1337     1339       +2     
  Branches      240      243       +3     
==========================================
  Hits         1170     1170              
+ Misses        116      115       -1     
- Partials       51       54       +3
Impacted Files Coverage Δ
gcovr/gcov.py 81.96% <ø> (ø) ⬆️
gcovr/txt_generator.py 86.36% <100%> (+8.18%) ⬆️
gcovr/html_generator.py 96.42% <100%> (+2.38%) ⬆️
gcovr/utils.py 61.93% <27.77%> (-4.49%) ⬇️
gcovr/__main__.py 88.32% <92.5%> (-0.23%) ⬇️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 6d8c00c...dfb74bd. Read the comment docs.

@mayeut

mayeut approved these changes Mar 6, 2018

@latk latk merged commit dfb74bd into gcovr:master Mar 6, 2018

2 of 4 checks passed

codecov/patch 74.19% of diff hit (target 87.5%)
Details
codecov/project 87.37% (-0.14%) compared to 6d8c00c
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details

@latk latk deleted the latk:grouped-options branch Mar 6, 2018

@latk latk referenced this pull request Mar 6, 2018

Closed

Clarify "exclude" options #151

@latk latk removed the needs review label Mar 6, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment