docs: modify documentation about custom time style

README.md

@@ -135,7 +135,7 @@ These options are available when running with `--long` (`-l`):
 - **--git-repos**: list each directory’s Git status, if tracked
 - **--git-repos-no-status**: list whether a directory is a Git repository, but not its status (faster)
 - **--no-git**: suppress Git status (always overrides `--git`, `--git-repos`, `--git-repos-no-status`)
-- **--time-style**: how to format timestamps. valid timestamp styles are ‘`default`’, ‘`iso`’, ‘`long-iso`’, ‘`full-iso`’, ‘`relative`', or you can use a `custom` style with '`+`' as prefix. (Ex: "`+%Y/%m/%d, %H:%M`" => "`2023/9/30, 12:00`"). [more about format syntax](https://docs.rs/chrono/latest/chrono/format/strftime/index.html).
+- **--time-style**: how to format timestamps. valid timestamp styles are ‘`default`’, ‘`iso`’, ‘`long-iso`’, ‘`full-iso`’, ‘`relative`’, or a custom style ‘`+<FORMAT>`’ (E.g., ‘`+%Y-%m-%d %H:%M`’ => ‘`2023-09-30 13:00`’. For more specifications on the format string, see the _`eza(1)` manual page_ and [chrono documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html).).
 - **--total-size**: show recursive directory size
 - **--no-permissions**: suppress the permissions field
 - **-o**, **--octal-permissions**: list each file's permission in octal format

completions/bash/eza

@@ -34,7 +34,7 @@ _eza() {
             ;;
 
         --time-style)
-            mapfile -t COMPREPLY < <(compgen -W 'default iso long-iso full-iso relative --' -- "$cur")
+            mapfile -t COMPREPLY < <(compgen -W 'default iso long-iso full-iso relative +FORMAT --' -- "$cur")
             return
             ;;
 

completions/fish/eza.fish

@@ -103,6 +103,7 @@ complete -c eza -l time-style -d "How to format timestamps" -x -a "
     long-iso\t'Display longer ISO timestamps, up to the minute'
     full-iso\t'Display full ISO timestamps, up to the nanosecond'
     relative\t'Display relative timestamps'
+    +FORMAT\t'Use custom time style'
 "
 complete -c eza -l total-size -d "Show recursive directory size (unix only)"
 complete -c eza -l no-permissions -d "Suppress the permissions field"

completions/zsh/_eza

@@ -49,7 +49,7 @@ __eza() {
         {-n,--numeric}"[List numeric user and group IDs.]" \
         {-S,--blocksize}"[List each file's size of allocated file system blocks.]" \
         {-t,--time}="[Which time field to show]:(time field):(accessed changed created modified)" \
-        --time-style="[How to format timestamps]:(time style):(default iso long-iso full-iso relative)" \
+        --time-style="[How to format timestamps]:(time style):(default iso long-iso full-iso relative +FORMAT)" \
         --total-size="[Show recursive directory size (unix only)]" \
         --no-permissions"[Suppress the permissions field]" \
         {-o,--octal-permissions}"[List each file's permission in octal format]" \

man/eza.1.md

@@ -214,7 +214,11 @@ These options are available when running with `--long` (`-l`):
 `--time-style=STYLE`
 : How to format timestamps.
 
-: Valid timestamp styles are ‘`default`’, ‘`iso`’, ‘`long-iso`’, ‘`full-iso`’, ‘`relative`', or you can use a `custom` style with '`+`' as prefix. (Ex: "`+%Y/%m/%d, %H:%M`" => "`2023/9/30, 12:00`"). for more details about format syntax, please read: https://docs.rs/chrono/latest/chrono/format/strftime/index.html
+: Valid timestamp styles are ‘`default`’, ‘`iso`’, ‘`long-iso`’, ‘`full-iso`’, ‘`relative`’, or a custom style ‘`+<FORMAT>`’ (e.g., ‘`+%Y-%m-%d %H:%M`’ => ‘`2023-09-30 13:00`’).
+
+`<FORMAT>` should be a chrono format string.  For details on the chrono format syntax, please read: https://docs.rs/chrono/latest/chrono/format/strftime/index.html .
+
+Alternatively, `<FORMAT>` can be a two line string, the first line will be used for non-recent files and the second for recent files.  E.g., if `<FORMAT>` is "`%Y-%m-%d %H<newline>--%m-%d %H:%M`", non-recent files => "`2022-12-30 13`", recent files => "`--09-30 13:34`".
 
 `--total-size`
 : Show recursive directory size (unix only).

src/options/help.rs

@@ -68,8 +68,8 @@ LONG VIEW OPTIONS
   -U, --created              use the created timestamp field
   --changed                  use the changed timestamp field
   --time-style               how to format timestamps (default, iso, long-iso,
-                             full-iso, relative, or a custom style with '+' as
-                             prefix. Ex: '+%Y/%m/%d')
+                             full-iso, relative, or a custom style '+<FORMAT>'
+                             like '+%Y-%m-%d %H:%M')
   --total-size               show the size of a directory as the size of all
                              files and directories inside (unix only)
   --no-permissions           suppress the permissions field

src/output/time.rs

@@ -46,7 +46,9 @@ pub enum TimeFormat {
     /// Use a relative but fixed width representation.
     Relative,
 
-    /// Use a custom format
+    /// Use custom formats, optionally a different custom format can be
+    /// specified for recent times, otherwise the same custom format will be
+    /// used for both recent and non-recent times.
     Custom {
         non_recent: String,
         recent: Option<String>,