UCG(1)

🌸 ucg: the source-code grep bestie (UCG(1)) 🌸

hiii bestie, welcome to the UCG(1) page from the General Commands Manual — yes, that manual, and yes, we're doing this with sparkle. ✨

🌟 NAME

ucg — a grep-like tool for searching source code. That's the whole vibe: grep-like, but for source code, and it's iconic. 💅

🎀 SYNOPSIS

ucg [ OPTIONS ] PATTERN [ FILES OR DIRECTORIES ]

💖 DESCRIPTION

okay so 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. No cap, that's the spec. 🦋

✨ OPTIONS ✨

🔎 Searching:

• --[no]smart-case — Ignore case if PATTERN is all lowercase (default: enabled). Smart-case is literally doing the vibe check for you.
• -i, --ignore-case — Ignore case distinctions in PATTERN.
• -Q, --literal — Treat all characters in PATTERN as literal. No regex shenanigans.
• -w, --word-regexp — PATTERN must match a complete word. Whole word only, periodt.

📤 Search Output:

• --column — Print column of first match after line number.
• --nocolumn — Don't print column of first match (default). That's the default, bestie.

🎨 File presentation:

• --color, --colour — Render the output with ANSI color codes. Cute.
• --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. The [no] is doing a lot of work, iykyk.
• --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. Example is literal, don't come for me.
• --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. Like, fully ignore them. periodt.

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

bestie note: Mandatory or optional arguments to long options are also mandatory or optional for any corresponding short options. That's not me being extra, that's the manual. 💅

💀 EXIT STATUS

Exit status is 0 if any matches were found, 1 if no matches, 2 or greater on error. So if you get 2+, something went sideways, bestie. Don't ignore it. 😭

🗂️ 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. It's giving config file era. 💖

📝 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. So later wins, periodt. 🔥

🎨 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'. Slay. 🌈

🧸 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'. Exactly, no side quests. 🎀

🦋 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'. Not me obsessing over '?akefile*', it's just iconic. 💅

🐛 BUGS

Report bugs to ⟨https://github.com/gvansickle/ucg/issues⟩. Please don't suffer in silence, bestie. 🙈

👑 AUTHOR

ucg is written by Gary R. Van Sickle ⟨grvs@users.sourceforge.net⟩. Respect the author, periodt. 🫶

🌈 SEE ALSO

The official UniversalCodeGrep site ⟨https://github.com/gvansickle/ucg⟩ on GitHub.

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

okay that's the whole UCG(1) manual, bestie — source/version tag UCG(1), dated 2016-10-31. mwah 💖🫶