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

SEE ALSO

The official UniversalCodeGrep site <URL: https://github.com/gvansickle/ucg > on GitHub.

grep(1) pcre(3) pcre2(3)


 

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
Searching:
Search Output:
File presentation:
File/directory inclusion/exclusion:
File type specifications:
Performance tuning:
Miscellaneous:
Informational options:
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