README-GIT-REGEX

   1 Using "pcreposix" With Git
   2 ==========================
   3
   4 Having another tl;dr moment?  Skip to the "Making Git Use pcreposix"
   5 section at the end.
   6
   7 When building Git, if the `NO_REGEX` option has been set (to anything)
   8 the bundled "GNU C Library" regex files will be built and included in
   9 the build.
  10
  11 Even if you did not set `NO_REGEX` explicitly, it's set automatically
  12 for many platforms and forced on always for `Darwin` platforms (even if
  13 you set it to empty in a `config.mak` file) so you may have the bundled
  14 regex implementation in your Git build and not even realize it.
  15
  16 A Git using the bundled glibc regex implementation suffers from perniciously
  17 pathological performance problems peculiar to glibc's regex implementation.
  18
  19 See the `README.txt` file for an example of a regex that causes problems
  20 when using the bundled glibc regex implementation.
  21
  22
  23 You're Using It And Maybe You Don't Even Know
  24 ---------------------------------------------
  25
  26 You may have tried to use an alternative regex implementation only to have
  27 the Git build complain and tell you to set `NO_REGEX`.  Since Git v2.10.1
  28 Git requires support for the BSD extension `REG_STARTEND` option when
  29 calling the `regexec` function.
  30
  31 The bundled glibc regex provides this (poorly though, the only part of the
  32 `REG_STARTEND` emulation that works properly compared to the BSD original
  33 happens to be the single part that Git needs to work).
  34
  35 You may think you're unaffected because your platform's regex works fine
  36 and provides `REG_STARTEND`.  But if you happen to be running an older
  37 Darwin system with a perfectly fine regex, since Git v1.8.3.3 you've also
  38 been silently forced onto the bundled glibc even if you have explicitly
  39 set `NO_REGEX=` in your own `config.mak` file.
  40
  41 Git's `config.mak.uname` file automatically sets `NO_REGEX` for many
  42 systems, some of which are quite popular.  So there's a fair chance you're
  43 using the bundled version anyway and even if you're not, if your system
  44 uses glibc you're ending up with just a newer version of the same code.
  45
  46
  47 Git Accepted Alternative
  48 ------------------------
  49
  50 Git needs BREs (Basic Regular Expressions) and EREs (Extended Regular
  51 Expressions) to work and the POSIX-specified `REG_NEWLINE` option must work
  52 as required by POSIX and finally `REG_STARTEND` must work at least enough
  53 to prevent reading any bytes past the "end" of the `REG_STARTEND` setting.
  54
  55 The combination of the fully POSIX-compliant `REG_NEWLINE` behavior (when
  56 it's set, something like "[^a]" does NOT match a newline) together with
  57 the `REG_STARTEND` requirement seems to have knocked out an awful lot of
  58 alternative regex implementations.
  59
  60 But never fear, the bundled version is here.
  61
  62 See the `README.txt` file.  You don't want the regex implementation bundled
  63 with Git.  Too bad there's no `NO_REGEX = AnythingButGlibc` option.
  64
  65
  66 Making Git Use pcreposix
  67 ------------------------
  68
  69 Are you still having a tl;dr moment?  Then go grab the `config.mak` file in
  70 this repository now and read it and use it.
  71
  72 The unmodified "pcreposix" library does not work with Git.
  73
  74 The new "pcreposix" library provided by the enhancements in this repository
  75 does.
  76
  77 It should be as simple as setting `NO_REGEX=` in your own custom `config.mak`
  78 and then adding `-I $includedir/pcreposix` and `-L $libdir -l pcreposix -l pcre`
  79 in the right places.
  80
  81 And that will work for all platforms except `Darwin`.  Because the setting
  82 of `NO_REGEX = YesPlease` is incorrectly done in the `Makefile` rather than
  83 the `config.mak.uname` file for the `Darwin` platform only, additional
  84 contortions are required to get a Git build on `Darwin` to use the new
  85 "pcreposix" library in place of the bundled regex library.
  86
  87 Add the contents of the `config.mak` file in this repository to the end of your
  88  own (creating it if you don't have one already) in the top-level of the Git
  89  distribution you wish to build.
  90
  91 Adjust the `PCREPOSIXDIR` and optionally `PCREPOSIXINC` and/or `PCREPOSIXLIB`
  92 settings as required to reflect the location of new pcreposix and pcre
  93 libraries built to include the "pcreposix-compat" enhancements.
  94
  95 Please note that prior to Git v2.11.1, the t7810 test relied on some undefined
  96 behavior when testing a few of the grep patterns.  Most of this was corrected
  97 in Git version v2.11.1, but a few remain that can result in spurious test
  98 failures.  There is a patch in the `gitpatches` subdirectory that can be
  99 applied to v2.11.1 to eliminate the spurious failure when using the
 100 pcreposix-compat library as a regex.h substitute.  Git versions prior to
 101 v2.11.1 will experience more spurious test failures from the t7810-grep test
 102 which can also safely be ignored.  Current versions of the Git test suite code
 103 as of 2018-03 (approx. Git version 2.16.3) continue to rely on the same
 104 POSIX-undefined behavior in the t7810 test that's dealt with by the patch.