UCG

Section: User Commands (1)
Updated: 2016-10-31
Index Return to Main Contents

NAME

ucg - a grep-like tool for searching source code

SYNOPSIS

ucg [ OPTIONS ] PATTERN [ FILES OR DIRECTORIES ]

DESCRIPTION

ucg (UniversalCodeGrep) is an extremely fast grep-like tool specialized for searching large bodies of source code. It is intended to be largely command-line compatible with ack, to some extent with ag, and - where appropriate - with grep(1). Search patterns are specified as pcre(3) regular expressions.

OPTIONS

Searching:

--[no]smart-case: Ignore case if PATTERN is all lowercase (default: enabled).
-i, --ignore-case: Ignore case distinctions in PATTERN
-Q, --literal: Treat all characters in PATTERN as literal.
-w, --word-regexp: PATTERN must match a complete word.

Search Output:

--column: Print column of first match after line number.
--nocolumn: Don't print column of first match (default).

File presentation:

--color, --colour: Render the output with ANSI color codes.
--nocolor, --nocolour: Render the output without ANSI color codes.

File/directory inclusion/exclusion:

--[no]ignore-dir=NAME, --[no]ignore-directory=NAME: [Do not] exclude directories with NAME.
--exclude=GLOB, --ignore=GLOB: Files matching GLOB will be ignored.
--ignore-file=FILTER:FILTERARGS: Files matching FILTER:FILTERARGS (e.g. ext:txt,cpp) will be ignored.
--include=GLOB: Only files matching GLOB will be searched.
-k, --known-types: Only search in files of recognized types (default: on).
-n, --no-recurse: Do not recurse into subdirectories.
-r, -R , --recurse: Recurse into subdirectories (default: on).
--type=[no]TYPE: Include only [exclude all] TYPE files. Types may also be specified as --[no]TYPE.

File type specifications:

--type-add=TYPE:FILTER:FILTERARGS: Files FILTERed with the given FILTERARGS are treated as belonging to type TYPE. Any existing definition of type TYPE is appended to.
--type-del=TYPE: Remove any existing definition of type TYPE.
--type-set=TYPE:FILTER:FILTERARGS: Files FILTERed with the given FILTERARGS are treated as belonging to type TYPE. Any existing definition of type TYPE is replaced.

Performance tuning:

--dirjobs=NUM_JOBS: Number of directory traversal jobs (std::thread<>s) to use.
-j, --jobs=NUM_JOBS: Number of scanner jobs (std::thread<>s) to use.

Miscellaneous:

--noenv: Ignore .ucgrc configuration files.

Informational options:

-?, --help: Print a list of options.
--help-types, --list-file-types: Print a list of supported file types.
--usage: Print a brief usage message.
-V, --version: Print program version.

Mandatory or optional arguments to long options are also mandatory or optional for any corresponding short options.

EXIT STATUS

Exit status is 0 if any matches were found, 1 if no matches, 2 or greater on error.

FILES

ucg supports configuration files with the name .ucgrc in which command-line options can be stored on a per-user and per-directory-hierarchy basis.

Format:

.ucgrc files are text files with a simple format. Each line of text can be either:

*: A single-line comment. The line must start with a # and the comment continues for the rest of the line.
*: A command-line parameter. This must be exactly as if it was given on the command line.

Location and Read Order:

When ucg is invoked, it looks for command-line options from the following locations in the following order:

1.: The .ucgrc file in the user's $HOME directory, if any.
2.: The first .ucgrc file found, if any, by walking up the component directories of the current working directory. This traversal stops at either the user's $HOME directory or the root directory. This is the project config file, and is intended to live in the top-level directory of a project directory hierarchy.
3.: The command line itself.

Options read later will override earlier options.

Creating User-Defined File Types:

ucg supports the creation of user-defined file types with the following options:

--type-set=TYPE:FILTER:FILTERARGS
--type-add=TYPE:FILTER:FILTERARGS

Any number of type filters, in any combination, can be added to a single file TYPE.

Three types of FILTERs are currently supported:

*

ext (extension list)

*

is (literal filename)

*

glob (glob pattern)

Extension List Filter

The extension list filter allows you to specify a comma-separated list of file extensions which are to be considered as belonging to file type TYPE. For example:


ucg --type-set=type1:ext:abc,xqz,def --type1 'Pattern'

will search all files with extensions *.abc, *.xqz, and *.def in the directory tree rooted at the current working directory for the literal string 'Pattern'.

Literal Filename Filter

The literal filename filter simply specifies a single literal filename which is to be considered as belonging to file type TYPE.

Example:


ucg --type-add=autoconf:is:configure.ac --autoconf 'Pattern'

This will search only files named exactly 'configure.ac' for the literal string 'Pattern'.

Glob filter

The glob filter allows you to specify a glob pattern to match against filenames. If the glob matches, the file is considered as belonging to the file type TYPE.

Example:


ucg --type-set=mk:glob:?akefile* --mk 'Pattern'

This will search only files which match the shell glob pattern '?akefile*' (e.g. Makefile, makefile, Bakefile.bkl, etc.) for the literal string 'Pattern'

BUGS

Report bugs to <URL: https://github.com/gvansickle/ucg/issues >

AUTHOR

ucg is written by Gary R. Van Sickle <URL: grvs@users.sourceforge.net >.

EXIT STATUS

FILES

Format:
Location and Read Order:
Creating User-Defined File Types:
Extension List Filter
Literal Filename Filter
Glob filter

BUGS

AUTHOR

SEE ALSO

This document was created by