Re: Using VC for change descriptions

[Joseph Myers]

On Mon, 1 Jan 2018, Richard Stallman wrote:

>   > > However, if people write a set of scripts to search for all changes in 
>   > > a particular kind fo C entity, and likewise for each other language,
>   > > that would deal with the complexity once and for all.  That might be an
>   > > ok solution.
> 
>   > It's "git log -L :<funcname>:<file>".
> 
> It tries to do that job, and will work in most cases, but it won't
> reliably do the whole job.  It doesn't try.  Here's the documentation
> of that option:
> 
>            If “:<regex>” is given in place of <start> and <end>, it denotes
>            the range from the first funcname line that matches <regex>, up to
>            the next funcname line. “:<regex>” searches from the end of the
>            previous -L range, if any, otherwise from the start of file.
>            “^:<regex>” searches from the start of file.
> 
> So you have to specify the context that belongs to a particular _kind_
> of definition, and if that has changed, you won't find anything from
> before that.

The default regex for identifying funcname lines is good for a range of 
different types of entities and source languages.

> Another shortcoming is that you can't get a list of the entities
> changed in a given commit.  You can only ask about one name you are
> interested in.

If you use e.g. "git show" or "git diff" to look at the diffs for a given 
commit, the diff hunk headers show function names (with the same logic as 
git log -L for identifying the relevant function).

>                                          (If a particular project is using a 
>   > language for which that does not work well by default, that project can 
>   > add a .gitattributes file and provide instructions on what to add to 
>   > .git/config in your checkout to make -L work better for that language.)
> 
> Would you please email me the documentation for .gitattributes and
> these changes in .git/config?  I would like to see what this feature
> can and can't do.

>From "man gitattributes" (this applies to both diff hunk headers and git 
log -L):

       Defining a custom hunk-header
           Each group of changes (called a "hunk") in the textual diff output
           is prefixed with a line of the form:

               @@ -k,l +n,m @@ TEXT

           This is called a hunk header. The "TEXT" portion is by default a
           line that begins with an alphabet, an underscore or a dollar sign;
           this matches what GNU diff -p output uses. This default selection
           however is not suited for some contents, and you can use a
           customized pattern to make a selection.

           First, in .gitattributes, you would assign the diff attribute for
           paths.

               *.tex   diff=tex

           Then, you would define a "diff.tex.xfuncname" configuration to
           specify a regular expression that matches a line that you would
           want to appear as the hunk header "TEXT". Add a section to your
           $GIT_DIR/config file (or $HOME/.gitconfig file) like this:

               [diff "tex"]
                       xfuncname = "^(\\\\(sub)*section\\{.*)$"

           Note. A single level of backslashes are eaten by the configuration
           file parser, so you would need to double the backslashes; the
           pattern above picks a line that begins with a backslash, and zero
           or more occurrences of sub followed by section followed by open
           brace, to the end of line.

           There are a few built-in patterns to make this easier, and tex is
           one of them, so you do not have to write the above in your
           configuration file (you still need to enable this with the
           attribute mechanism, via .gitattributes). The following built in
           patterns are available:

           o   ada suitable for source code in the Ada language.

           o   bibtex suitable for files with BibTeX coded references.

           o   cpp suitable for source code in the C and C++ languages.

           o   csharp suitable for source code in the C# language.

           o   fortran suitable for source code in the Fortran language.

           o   fountain suitable for Fountain documents.

           o   html suitable for HTML/XHTML documents.

           o   java suitable for source code in the Java language.

           o   matlab suitable for source code in the MATLAB language.

           o   objc suitable for source code in the Objective-C language.

           o   pascal suitable for source code in the Pascal/Delphi language.

           o   perl suitable for source code in the Perl language.

           o   php suitable for source code in the PHP language.

           o   python suitable for source code in the Python language.

           o   ruby suitable for source code in the Ruby language.

           o   tex suitable for source code for LaTeX documents.

-- 
Joseph S. Myers
address@hidden