Merge pull request #902 from rpjday/searching

Minor aesthetic/rewording changes to "Searching" section in Chapter 7

Author: ben

book/07-git-tools/sections/searching.asc

@@ -1,18 +1,18 @@
 [[_searching]]
 === Searching
 
-With just about any size codebase, you'll often need to find where a function is called or defined, or find the history of a method.
+With just about any size codebase, you'll often need to find where a function is called or defined, or display the history of a method.
 Git provides a couple of useful tools for looking through the code and commits stored in its database quickly and easily.
 We'll go through a few of them.
 
 [[_git_grep]]
 ==== Git Grep
 
 Git ships with a command called `grep` that allows you to easily search through any committed tree or the working directory for a string or regular expression.
-For these examples, we'll look through the Git source code itself.
+For the examples that follow, we'll search through the source code for Git itself.
 
-By default, it will look through the files in your working directory.
-You can pass `-n` to print out the line numbers where Git has found matches.
+By default, `git grep` will look through the files in your working directory.
+As a first variation, you can use either of the `-n` or `--line-number` options to print out the line numbers where Git has found matches:
 
 [source,console]
 ----
@@ -21,45 +21,46 @@ compat/gmtime.c:3:#undef gmtime_r
 compat/gmtime.c:8:      return git_gmtime_r(timep, &result);
 compat/gmtime.c:11:struct tm *git_gmtime_r(const time_t *timep, struct tm *result)
 compat/gmtime.c:16:     ret = gmtime_r(timep, result);
-compat/mingw.c:606:struct tm *gmtime_r(const time_t *timep, struct tm *result)
-compat/mingw.h:162:struct tm *gmtime_r(const time_t *timep, struct tm *result);
-date.c:429:             if (gmtime_r(&now, &now_tm))
-date.c:492:             if (gmtime_r(&time, tm)) {
-git-compat-util.h:721:struct tm *git_gmtime_r(const time_t *, struct tm *);
-git-compat-util.h:723:#define gmtime_r git_gmtime_r
+compat/mingw.c:826:struct tm *gmtime_r(const time_t *timep, struct tm *result)
+compat/mingw.h:206:struct tm *gmtime_r(const time_t *timep, struct tm *result);
+date.c:482:             if (gmtime_r(&now, &now_tm))
+date.c:545:             if (gmtime_r(&time, tm)) {
+date.c:758:             /* gmtime_r() in match_digit() may have clobbered it */
+git-compat-util.h:1138:struct tm *git_gmtime_r(const time_t *, struct tm *);
+git-compat-util.h:1140:#define gmtime_r git_gmtime_r
 ----
 
-There are a number of interesting options you can provide the `grep` command.
+In addition to the basic search shown above, `git grep` supports a plethora of other interesting options.
 
-For instance, instead of the previous call, you can have Git summarize the output by just showing you which files matched and how many matches there were in each file with the `--count` option:
+For instance, instead of printing all of the matches, you can ask `git grep` to summarize the output by showing you only which files contained the search string and how many matches there were in each file with the `-c` or `--count` option:
 
 [source,console]
 ----
 $ git grep --count gmtime_r
 compat/gmtime.c:4
 compat/mingw.c:1
 compat/mingw.h:1
-date.c:2
+date.c:3
 git-compat-util.h:2
 ----
 
-If you want to see what method or function it thinks it has found a match in, you can pass `-p`:
+If you're interested in the _context_ of a search string, you can display the enclosing method or function for each matching string with either of the `-p` or `--show-function` options:
 
 [source,console]
 ----
 $ git grep -p gmtime_r *.c
-date.c=static int match_multi_number(unsigned long num, char c, const char *date, char *end, struct tm *tm)
+date.c=static int match_multi_number(timestamp_t num, char c, const char *date,
 date.c:         if (gmtime_r(&now, &now_tm))
 date.c=static int match_digit(const char *date, struct tm *tm, int *offset, int *tm_gmt)
 date.c:         if (gmtime_r(&time, tm)) {
+date.c=int parse_date_basic(const char *date, timestamp_t *timestamp, int *offset)
+date.c:         /* gmtime_r() in match_digit() may have clobbered it */
 ----
 
-So here we can see that `gmtime_r` is called in the `match_multi_number` and `match_digit` functions in the `date.c` file.
+As you can see, the `gmtime_r` routine is called from both the `match_multi_number` and `match_digit` functions in the `date.c` file (the third match displayed represents just the string appearing in a comment).
 
-You can also look for complex combinations of strings with the `--and` flag, which makes sure that multiple matches are in the same line.
-For instance, let's look for any lines that define a constant with either the strings ``LINK'' or ``BUF_MAX'' in them in the Git codebase in an older 1.8.0 version.
-
-Here we'll also use the `--break` and `--heading` options which help split up the output into a more readable format.
+You can also search for complex combinations of strings with the `--and` flag, which ensures that multiple matches must occur in the same line of text.
+For instance, let's look for any lines that define a constant whose name contains _either_ of the substrings ``LINK'' or ``BUF_MAX'', specifically in an older version of the Git codebase represented by the tag `v1.8.0` (we'll throw in the `--break` and `--heading` options which help split up the output into a more readable format):
 
 [source,console]
 ----
@@ -95,7 +96,7 @@ As we saw in the above example, we looked for terms in an older version of the G
 Perhaps you're looking not for _where_ a term exists, but _when_ it existed or was introduced.
 The `git log` command has a number of powerful tools for finding specific commits by the content of their messages or even the content of the diff they introduce.
 
-If we want to find out for example when the `ZLIB_BUF_MAX` constant was originally introduced, we can use the `-S` option (colloquially referred to as the Git "pickaxe" option) to tell Git to show us only those commits that changed the number of occurrences of that string.
+If, for example, we want to find out when the `ZLIB_BUF_MAX` constant was originally introduced, we can use the `-S` option (colloquially referred to as the Git ``pickaxe'' option) to tell Git to show us only those commits that changed the number of occurrences of that string.
 
 [source,console]
 ----
@@ -104,7 +105,7 @@ e01503b zlib: allow feeding more than 4GB in one go
 ef49a7a zlib: zlib can only process 4GB at a time
 ----
 
-If we look at the diff of those commits we can see that in `ef49a7a` the constant was introduced and in `e01503b` it was modified.
+If we look at the diff of those commits, we can see that in `ef49a7a` the constant was introduced and in `e01503b` it was modified.
 
 If you need to be more specific, you can provide a regular expression to search for with the `-G` option.
 
@@ -154,6 +155,6 @@ diff --git a/zlib.c b/zlib.c
 +
 ----
 
-If Git can't figure out how to match a function or method in your programming language, you can also provide it a regex.
-For example, this would have done the same thing: `git log -L '/unsigned long git_deflate_bound/',/^}/:zlib.c`.
+If Git can't figure out how to match a function or method in your programming language, you can also provide it with a regular expression (or _regex_).
+For example, this would have done the same thing as the example above: `git log -L '/unsigned long git_deflate_bound/',/^}/:zlib.c`.
 You could also give it a range of lines or a single line number and you'll get the same sort of output.