What is "the function name regex" for git log -L :<funcname>:<file>

Question

I have the following Swift function in my file Main/VProj/AppModel.swift

    func createItemAndSegment(image:UIImage, completionHandler:(Item?, NSError?)->Void) {
        \\[...]
    }

The documentation for git log -L :<funcname>:<file> states

-L <start>,<end>:<file>

-L :<funcname>:<file>

Trace the evolution of the line range given by "<start>,<end>" (or the function name regex <funcname>) within the <file>.

But the commands

• git log -L :createItemAndSegment:Main/VProj/AppModel.swift
• git log -L :'createItemAndSegment':Main/VProj/AppModel.swift
• git log -L :'/createItemAndSegment/':Main/VProj/AppModel.swift

all fail with the error starting at line 1: no match

When the documentation says :<funcname> is the "function name regex", what should it look like?

Answer 1

The funcname should be a regular expression that matches the function name, and a literal string with no special regular expression characters should be a valid regular expression, so your first example, git log -L :createItemAndSegment:Main/VProj/AppModel.swift, should work.

However, in order for it to work, Git needs to be able to determine which lines are function declarations. It has a default regular expression that assumes that any line that begins with an alphabetic character, underscore, or dollar sign (with no leading whitespace) is the start of a function declaration, and using the -L :<funcname>:<file> syntax will be searching for a function declaration that also matches your pattern, up to the next function declaration or end of file.

In some languages, this heuristic is not appropriate. For instance, if function or method declarations are nested inside of a class and thus indented, it will not pick up on these declarations. For this, you need to define a custom function header regex. The .gitattributes section "Defining a custom hunk-header" describes how to do this. First, you would create a .gitattributes file at the top level of your project that contains something like:

*.swift diff=swift

Then in your .git/config, or your global ~/.gitconfig, you would define a regex for how to find these declarations. I don't know enough of Swift to be able to tell you for sure what the appropriate regex is, but it might be something like the following (which I based on the built in regex for Python):

[diff "swift"]
    xfuncname = ^[ \t]*((class|func)[ \t].*)$