feat(blame): support format strings

- config.current_line_blame_formatter can now be specified as a format
string.

- changed default of `config.current_line_blame_formatter` to
  '<author>, <author_time:%R> - <summary>' which is equivalent to the
  previous function default.

- deprecated config.current_line_blame_formatter_opts

Resolves #291

README.md

@@ -105,9 +105,7 @@ require('gitsigns').setup {
     delay = 1000,
     ignore_whitespace = false,
   },
-  current_line_blame_formatter_opts = {
-    relative_time = false
-  },
+  current_line_blame_formatter = '<author>, <author_time:%Y-%m-%d> - <summary>',
   sign_priority = 6,
   update_debounce = 100,
   status_formatter = nil, -- Use default

doc/gitsigns.txt

@@ -57,9 +57,7 @@ of the default settings:
         delay = 1000,
         ignore_whitespace = false,
       },
-      current_line_blame_formatter_opts = {
-        relative_time = false
-      },
+      current_line_blame_formatter = '<author>, <author_time:%Y-%m-%d> - <summary>',
       sign_priority = 6,
       update_debounce = 100,
       status_formatter = nil, -- Use default
@@ -658,6 +656,8 @@ current_line_blame_opts              *gitsigns-config-current_line_blame_opts*
 
 current_line_blame_formatter_opts
                            *gitsigns-config-current_line_blame_formatter_opts*
+   DEPRECATED
+
       Type: `table[extended]`
       Default: >
         {
@@ -670,61 +670,81 @@ current_line_blame_formatter_opts
         • relative_time: boolean
 
 current_line_blame_formatter    *gitsigns-config-current_line_blame_formatter*
-      Type: `function`
-      Default: >
-        function(name, blame_info, opts)
-          if blame_info.author == name then
-            blame_info.author = 'You'
-          end
+      Type: `string|function`, Default: `' <author>, <author_time:%Y-%m-%d> - <summary>'`
 
-          local text
-          if blame_info.author == 'Not Committed Yet' then
-            text = blame_info.author
-          else
-            local date_time
-
-            if opts.relative_time then
-              date_time = require('gitsigns.util').get_relative_time(tonumber(blame_info['author_time']))
-            else
-              date_time = os.date('%Y-%m-%d', tonumber(blame_info['author_time']))
-            end
-
-            text = string.format('%s, %s - %s', blame_info.author, date_time, blame_info.summary)
-          end
-
-          return {{' '..text, 'GitSignsCurrentLineBlame'}}
-        end
-<
-      Function used to format the virtual text of
+      String or function used to format the virtual text of
       |gitsigns-config-current_line_blame|.
 
-      Parameters: ~
-        {name}       Git user name returned from `git config user.name` .
-        {blame_info} Table with the following keys:
-                       • `abbrev_sha`: string
-                       • `orig_lnum`: integer
-                       • `final_lnum`: integer
-                       • `author`: string
-                       • `author_mail`: string
-                       • `author_time`: integer
-                       • `author_tz`: string
-                       • `committer`: string
-                       • `committer_mail`: string
-                       • `committer_time`: integer
-                       • `committer_tz`: string
-                       • `summary`: string
-                       • `previous`: string
-                       • `filename`: string
-
-                     Note that the keys map onto the output of:
-                       `git blame --line-porcelain`
-
-        {opts}       Passed directly from
-                     |gitsigns-config-current_line_blame_formatter_opts|.
-
-      Return: ~
-        The result of this function is passed directly to the `opts.virt_text`
-        field of |nvim_buf_set_extmark|.
+      When a string, accepts the following format specifiers:
+
+          • `<abbrev_sha>`
+          • `<orig_lnum>`
+          • `<final_lnum>`
+          • `<author>`
+          • `<author_mail>`
+          • `<author_time>` or `<author_time:FORMAT>`
+          • `<author_tz>`
+          • `<committer>`
+          • `<committer_mail>`
+          • `<committer_time>` or `<committer_time:FORMAT>`
+          • `<committer_tz>`
+          • `<summary>`
+          • `<previous>`
+          • `<filename>`
+
+        For `<author_time:FORMAT>` and `<committer_time:FORMAT>`, `FORMAT` can
+        be any valid date format that is accepted by `os.date()` with the
+        addition of `%R`:
+
+          • `%a`  abbreviated weekday name (e.g., Wed)
+          • `%A`  full weekday name (e.g., Wednesday)
+          • `%b`  abbreviated month name (e.g., Sep)
+          • `%B`  full month name (e.g., September)
+          • `%c`  date and time (e.g., 09/16/98 23:48:10)
+          • `%d`  day of the month (16) [01-31]
+          • `%H`  hour, using a 24-hour clock (23) [00-23]
+          • `%I`  hour, using a 12-hour clock (11) [01-12]
+          • `%M`  minute (48) [00-59]
+          • `%m`  month (09) [01-12]
+          • `%p`  either "am" or "pm" (pm)
+          • `%S`  second (10) [00-61]
+          • `%w`  weekday (3) [0-6 = Sunday-Saturday]
+          • `%x`  date (e.g., 09/16/98)
+          • `%X`  time (e.g., 23:48:10)
+          • `%Y`  full year (1998)
+          • `%y`  two-digit year (98) [00-99]
+          • `%%`  the character `%´
+          • `%R`  relative (e.g., 4 months ago)
+
+      When a function:
+        Parameters: ~
+          {name}       Git user name returned from `git config user.name` .
+          {blame_info} Table with the following keys:
+                         • `abbrev_sha`: string
+                         • `orig_lnum`: integer
+                         • `final_lnum`: integer
+                         • `author`: string
+                         • `author_mail`: string
+                         • `author_time`: integer
+                         • `author_tz`: string
+                         • `committer`: string
+                         • `committer_mail`: string
+                         • `committer_time`: integer
+                         • `committer_tz`: string
+                         • `summary`: string
+                         • `previous`: string
+                         • `filename`: string
+
+                       Note that the keys map onto the output of:
+                         `git blame --line-porcelain`
+
+          {opts}       Passed directly from
+                       |gitsigns-config-current_line_blame_formatter_opts|.
+
+        Return: ~
+          The result of this function is passed directly to the `opts.virt_text`
+          field of |nvim_buf_set_extmark| and thus must be a list of
+          [text, highlight] tuples.
 
 trouble                                              *gitsigns-config-trouble*
       Type: `boolean`, Default: true if installed

gen_help.lua

@@ -87,7 +87,7 @@ local function get_default(field)
     local l = cfg[i]
     if l:match('^    default =') then
       ds = i
-      if l:match('},') or l:match('nil,') then
+      if l:match('},') or l:match('nil,') or l:match("default = '.*'") then
         de = i
         break
       end
@@ -172,6 +172,9 @@ local function gen_config_doc_field(field, out)
       if v.type == 'table' and v.deep_extend then
         return 'table[extended]'
       end
+      if type(v.type) == 'table' then
+        v.type = table.concat(v.type, '|')
+      end
       return v.type
     end)()