Clarify regex flavor and mechanics in docs

[zeromask1337]

Is your feature request related to a problem? Please describe.
Right now docs doesn't clarify what flavor of regex lazygit is using. It results in many hours of trying different combination that ends with frustration. We need a way to make this process less painfull.

Describe the solution you'd like
For a minimum requirement I suggest providing explanation of regex flavor that is being used. I tried Golang one, but failed. We need more examples with popular variants, and also some quickfixes for most popular prefix problems.
We can also add custom script with real time regex test, that runs on existing branches.

Describe alternatives you've considered
I considered using custom script, but it seems little bit overkill for what we are trying to achieve

Additional context
I tried this config

gui:
  branchColors:
    "feature": "#11aaff"
git:
  commitPrefixes:
    some-front:
      pattern: ([a-zA-Z0-9]+-?\\d+)
      replace: '[$1] '
    shopping-2:
      pattern: ^feature/([A-Z]+-\d+)
      replace: '[$1] '
    shopping-3:
      pattern: ^feature/[A-Z]+-\d+$
      replace: '[$1] '

with this branches

feature/SHOP-1111_foo_bar_baz
feature/SHOP-1111foobarbaz
feature/SHOP-1111123123

None of them matched

[stefanhaller]

I suspect that the regex flavor is not your problem here. Lazygit uses golang's regex package, so it uses the syntax described here.

Are you aware that the commitPrefixes is a map keyed by the repo name? Your first pattern in the config above would only match in a repo whose name is "some-front". Is that what you want? If you want to define a prefix globally, use the commitPrefix config (singular).

[zeromask1337]

some-front is one of my working folders. Its renamed for the sake of privacy. It doesn't match either in lazygit, so its not the naming problem. If its not flavor, than I suspect its something with yaml parsing or the prefix matching itself.

[stefanhaller]

Ok. In that case, it's just basic regex errors that make this not work for you. I'm not sure what lazygit or its documentation can do to help with this; regex is hard. 😄 I recommend https://regex101.com to test your patterns.

Your first pattern doesn't work because of the double backslash; there's no reason to quote backslashes in yaml (unless you put them in double quotes, which is not a good idea for regex patterns. You'd have to escape too many things in the pattern.)

Your second pattern does work for me; however, it results in a subject line of "[SHOP-1111] _foo_bar_baz", which I suspect is not what you want. Use ^feature/([A-Z]+-\d+).*$ to only get "[SHOP-1111] ".

The third pattern doesn't work because it anchors to the end of the string after \d+.

Finally, one word about testing these in lazygit: I was briefly confused why changing the config while lazygit is running didn't seem to have any effect (normally, config changes are supposed to take effect immediately). The reason is lazygit's feature to remember a half-typed commit message when you abort committing. When I tested this, I staged a file, hit c to see what commit message I got, and then hit esc to close the editor. Then, when I changed the pattern in the config and tried again, I would get that same message again because lazygit helpfully remembered it for me, which is confusing in this case. You can avoid this by pressing ctrl-U to delete the subject before you hit esc.

[zeromask1337]

Yeah, lazygit config taking effect after restart is something to keep in mind. And likely to specify in docs. After I restarted changes took effect. BTW I'm using git flow, and I think it has its part in affecting overall regex story. Lets reproduce:

Without capture group

Project: shopping-2
Branch: feature/SHOP-1111_foo_bar_baz
Regex:

git:
  commitPrefixes:
    shopping-2:
      pattern: ^feature/[A-Z]+-\d+
      replace: '[$1] '

Regex101 test:

[
  [
    {
      "content": "feature/SHOP-1111",
      "isParticipating": true,
      "groupNum": 0,
      "startPos": 0,
      "endPos": 23
    }
  ]
]

Press c to commit results in:

[] _foo_bar_baz

With capture group

Project: shopping-2
Branch: feature/SHOP-1111_foo_bar_baz
Regex:

git:
  commitPrefixes:
    shopping-2:
      pattern: ^feature/([A-Z]+-\d+)
      replace: '[$1] '

Regex101 test:

[
  [
    {
      "content": "feature/SHOP-1111",
      "isParticipating": true,
      "groupNum": 0,
      "startPos": 0,
      "endPos": 17
    },
    {
      "content": "SHOP-1111",
      "isParticipating": true,
      "groupNum": 1,
      "startPos": 8,
      "endPos": 17
    }
  ]
]

Press c to commit results in:

[SHOP-1111] _foo_bar_baz

To summarize

As you can see, regex is acting strange. Without group it doesnt match SHOP-1111, and only returns brackets AND rest of branch name. That is something I dont understand, because we didn't specify it in config. But with grouping regex match seems to work.

My overall goal was to capture feature/SHOP-1111 part of branch, but it doesn't work in any of solutions.

[stefanhaller]

Yeah, lazygit config taking effect after restart is something to keep in mind. And likely to specify in docs.

No, config changes do take effect without restart. The fact that this doesn't work for the commit prefix patterns has to do with the preserve commit message functionality; the two interfere in ways that are hard to understand. Actually this may be a bug, I'll see if I can come up with an easy fix.

BTW I'm using git flow, and I think it has its part in affecting overall regex story.

Huh? I don't see what that has to do with it.

As you can see, regex is acting strange. Without group it doesnt match SHOP-1111, and only returns brackets AND rest of branch name. That is something I dont understand,

That's how regex replacing works in go. When you use $n in the replacement string, where n is a number, it puts the nth captured subgroup at that place. If n is out of range because there aren't that many capture groups in the regex, it puts an empty string there.

My overall goal was to capture feature/SHOP-1111 part of branch, but it doesn't work in any of solutions.

Try this:

      pattern: ^(feature/[A-Z]+-\d+).*$
      replace: '[$1] '

[stefanhaller]

The fact that this doesn't work for the commit prefix patterns has to do with the preserve commit message functionality; the two interfere in ways that are hard to understand. Actually this may be a bug, I'll see if I can come up with an easy fix.

Here's a fix for this problem: #4110.

[zeromask1337]

Great! Thank you for the explanation, I managed to get my regex working. Also I made a doc PR that helps other users handle this issue #4114