BK-GREP(1)

🌸 bk grep — the manual, but make it make sense 💅

okay bestie, real talk: this is the page for bk grep, and it lives in the BitKeeper User's Manual. Yes, that BitKeeper. Yes, the one your team lead keeps romanticising. Sit down, grab a strawberry 🍓, and let's get into it.

---

✨ NAME ✨

bk grep — search some or all revisions of one or more files for a pattern 🔎

---

🦋 SYNOPSIS 🦋

bk grep [options] pattern [file ... | -]

---

🎀 DESCRIPTION 🎀

So the bk grep command searches the named files — or standard input if you hand it the file name -, iconic — for lines containing a match to the given pattern. The pattern may be a perl compatible regular expression. By default, bk grep prints the matching lines. Simple. Clean. Slay.

Now here's the part where it eats: while it's designed to be command line compatible with GNU grep, bk grep can search in the most recent revision of a file, all revisions of a file, a subset of revisions of a file, or the checked out and (possibly) modified version of a file. That's range, bestie. That's main character energy. 👑

By default, bk grep searches the checked out version of a file — and if that isn't present, then it searches the most recent version of the file. The -r, -R, and -c options are the ones that control where in a file's history to search. Remember those three, they're literally the whole personality of this command.

The printed lines may be annotated with file names, dates, revision numbers, line numbers, and/or user names. Cute little labels. We love a labelled moment. 🏷️

---

💖 OPTIONS 💖

• -Anum — Print num lines of trailing context after matching lines. Places a line containing -- between contiguous groups of matches. (Like GNU grep.) ✨
• -Abdnpru — Annotate the output with information from the revision history. Each annotation is aligned in a column. The option argument[s] turn on one or more annotations as a prefix to each line. The order of fields is fixed (no matter what order you specify them) and is the same as the order listed below:
  • p — Prefix each line with the pathname of the file relative to the current working directory. The name is always the current name of the file even if it has been renamed. 👀
  • d — Prefix each line with the date of last modification.
  • u — Prefix each line with the name of the user who last modified it.
  • r — Prefix each line with the revision of last modification.
  • n — Prefix each line with its line number.

🚨 This option is incompatible with the -A/-B/-C context options — use -a if you need more lines of context. Not me warning you twice.

• -adnpru — Similar to -A but each annotation is followed by a colon rather than a set of spaces aligning the output. The order of fields is fixed (no matter what order you specify them) and is: pathname, date, user, revision, line number. 🫶
• -Bnum — Print num lines of leading context before matching lines. Places a line containing -- between contiguous groups of matches. (Like GNU grep.)
• -C[num] — Print num lines of output context. Places a line containing -- between contiguous groups of matches. If no value is given, defaults to 2. (Like GNU grep.) 🎀
• -cdates — Select the versions to search as all deltas created in the specified range of dates. (Different than GNU grep — don't @ me.)
• -h — Do not print filenames with matches when multiple files are searched. Normally, if more than one file is searched, the results are prefixed with the filename. (Like GNU grep.)
• -H — Print the file name even if there is only one file being searched. Normally, if only one file is searched, then the file name is skipped unless it was explicitly selected. (Like GNU grep.)
• -i — Ignore case distinctions in both the pattern and the input files. (Like GNU grep.) iykyk
• -l — Suppress normal output; instead print the name of each input file from which output would have normally been produced. (Like GNU grep.)
• -L — Suppress normal output; instead print the name of each input file from which no output would have normally been produced. (Like GNU grep.) The lowercase/uppercase flip here is lowkey evil but it's fine.
• -n — Prefix each line with the line number from its input file. (Like GNU grep.)
• -q — Do not produce any output. Exit immediately with zero status if any match is found. (Like GNU grep.) The quiet quitting option 💀
• -rrev — Only look in revision rev for the pattern.
• -R[rev] — Only look in range of revisions rev for the pattern. If rev is not specified, that implies all versions of the file[s]. The difference between this option and the previous option is that in this case bk grep looks in the lines added by the specified revision, but in the -r case, the entire contents of the specified version is searched. Big difference, bestie, do not confuse them. 🧚
• -v — Invert the sense of matching, to select non-matching lines. (Like GNU grep.)
• -x — Select only those matches that exactly match the whole line. (Like GNU grep.)

---

🌈 EXIT STATUS 🌈

bk grep returns exit status:

• 0 — if any matches were found ✅
• 1 — if no matches were found 😭
• 2 — if an error occurred 💀

---

🔥 EXAMPLES 🔥

Look for a pattern in the working copy of a file:

$ bk grep pattern foo.c

Look for a pattern in the most recent checked in version of a file:

$ bk grep -r+ pattern foo.c

Look for a pattern in all checked in versions of a file (this searches every line ever present in the file, even if some lines have been deleted):

$ bk grep -R pattern foo.c

Look for a pattern in all files in the current working directory:

$ bk grep pattern

Look for a pattern in any version of any file in your tree (including deleted files; if this doesn't find it then pattern was never present in your history):

$ bk -A grep -R pattern

To see if it occurs in the most recent version of of any file of your tree:

$ bk -A grep -r+ pattern

To see if it occurs anywhere in any of your checked out files (this may be substantially faster than searching all files because it skips files not checked out):

$ bk -UG grep pattern

To see if it was added by the most recent delta made in of any active (undeleted) file of your tree:

$ bk -U grep -R+ pattern

See if a pattern was added in the last year (skips deleted files):

$ bk -U grep -c-1y pattern

See if a pattern was added between June 1 of 2010 and July 31 of 2010:

$ bk -U grep -c2010/06..2010/07

See if a pattern was added between two tagged releases:

$ bk -U grep -Rbk-4.6..bk-5.0

See if you left some debugging in the modified files (we tend to add fprintf(stderr, "DEBUG stuff0) statements but left justify them so we can find them):

$ bk -cU grep 'ˆfprintf'

---

🐛 BUGS 🐛

The ways of specifying which versions to search are non-obvious. You need to read the examples carefully. We made the default be the most useful/common one. That's the whole bug report, bestie, I don't make the rules. 🙈

Binary files are never searched, they are silently ignored. Not a peep. Not a whisper. Just vibes and silence. 💀

---

👑 SEE ALSO 👑

bk-annotate, bk-bk, bk-cat, bk-get, bk-pcre, bk-range

---

⭐ CATEGORY ⭐

File

---

okay that's the whole page, you're officially a bk grep girlie now, go forth and search your history with confidence 🫶✨

with love, BitKeeper Inc — version 1E1, dated 1E1, mwah 💋