Basic documentation.

This is still a work-in-progress, and very incomplete, but at least it is
something to have as a reference.

README.md

@@ -0,0 +1,48 @@
+<h1 align="center">Summer</h1>
+
+<p align="center">
+    <img alt="Example" src="./examples/demo.svg" />
+</p>
+
+---
+
+Summer is a [CLI] application that reads the contents of a directory, and
+generates a summary based on a custom configuration.
+
+:warning: *This README is a work-in-progress*
+
+# Features
+
+- Files and subdirectories can be matched by file name (either by glob or regex
+  patterns), file type, MIME types, modification time, and git status.
+
+- Matchers are used to organize files and subdirectories in columns, to apply
+  styles, and to compute stats.
+
+- The summary can include a header and an extra column with computed stats.
+
+The screenshot at the top is generated using the [`filetypes.yaml` example].
+
+# Installation
+
+The [Releases page] contains precompiled packages for multiple operating
+systems.
+
+# Usage
+
+Unfortunately, a proper documentation for the tool is still pending. The file
+[`summer.yaml`] contains an explanation of every possible configuration setting,
+and there are some examples in the [`examples`] directory.
+
+The configuration file is set with the `-c` option.
+
+If you invoke `summer` with no arguments, the configuration is read from the
+`<config>/summer/config.yaml`, where `<config>` is the value from
+[`dirs::config_dir`] (for example, `~/.config/summer/config.yaml` in Linux).
+
+[CLI]: https://en.wikipedia.org/wiki/Command-line_interface
+[Releases page]: https://github.com/ayosec/summer/releases
+[`dirs::config_dir`]: https://docs.rs/dirs/4.0.0/dirs/fn.config_dir.html
+[`examples`]: ./examples/
+[`filetypes.yaml` example]: ./examples/filetypes.yaml
+[`summer.yaml`]: ./summer.yaml

examples/filetypes.yaml

@@ -0,0 +1,61 @@
+# Configuration example using file types.
+
+colors:
+  use_lscolors: no
+  column_label: ul cyan
+
+  styles:
+    # Directories.
+    - matchers: [ type: directory ]
+      indicator: 📁
+      color: blue
+
+    # Executable files.
+    - matchers: [ type: executable ]
+      indicator: 💡
+      color: green
+
+    # Hidden files.
+    - matchers: [ regex: '^\.' ]
+      color: "#999999"
+
+    # Hidden directories.
+    - matchers: [ all: [ type: directory, regex: '^\.' ] ]
+      color: "#555588"
+
+columns:
+  - label: Dirs
+    matchers: [ type: directory ]
+    include_hidden: true
+
+  - label: Text
+    matchers:
+    - regex: '\A[A-Z0-9]+\z'
+    - mime: text
+
+  - label: Media
+    matchers: [ mime: audio, mime: image, mime: video ]
+
+  - label: Others
+    matchers: [ any ]
+    include_hidden: true
+    exclude:
+      - glob: '*.swp'
+
+info:
+  right: "%C{magenta}%P"
+
+  column: |-
+    %C{red}%V{dirs}%C{reset} directories
+    %C{red}%S%C{reset} in %C{red}%V{files}%C{reset} files
+    %C{red}%V{hidden}%C{reset} hidden
+
+    %C{red}%V{images}%C{reset} media files
+    %C{red}%V{text}%C{reset} text files
+
+  variables:
+    dirs: [ type: directory ]
+    files: [ type: file ]
+    hidden: [ regex: '\A\.' ]
+    images: [ mime: audio, mime: image, mime: video ]
+    text: [ mime: text ]

examples/git-focus.yaml

@@ -0,0 +1,56 @@
+# This example configuration uses features around Git.
+
+colors:
+  column_label: bold ul
+  more_entries: italic magenta
+  name_ellipsis: red
+
+  styles:
+    # Highlight the .git directory.
+    - matchers:
+      - all:
+        - type: directory
+        - glob: .git
+      color: white blue
+
+    # Add a yellow diamond for files modified in the last day.
+    - matchers: [ changes: 1 day ]
+      indicator:
+        text: ◆
+        color: yellow
+
+columns:
+  - label: Git
+    include_hidden: true
+    matchers: [ changes: git ]
+
+  - label: Dirs
+    matchers: [ type: directory ]
+
+  - label: Files
+    matchers: [any ]
+    include_hidden: true
+    exclude: [ glob: "*.swp" ]
+
+grid:
+  max_rows: 30
+  max_name_width: 20
+
+info:
+  variables:
+    # Count how many files have changes in git.
+    files_git: [ changes: git ]
+
+  # Left header: just the path to the directory.
+  left: "\n%C{magenta}%P"
+
+  # Right header: a summary of the git-diff stats.
+  right:
+    color: "black #eeeeee"
+    text: "\n %C{green}+%+%C{reset} %C{red}+%-%C{reset} in %C{bold}%V{files_git}%C{reset} files \n"
+
+collector:
+  # Wait up to two seconds to get disk usage and git-diff stats.
+  timeout: 2s
+  disk_usage: true
+  git_diff: true

summer.yaml

@@ -0,0 +1,147 @@
+# Configuration file for Summer.
+#
+# This is a reference file. Use it to build your own settings.
+
+# List of columns to build the summary of the directory.
+#
+columns:
+  - matchers: [ any ]
+
+  # If `false`, always ignore hidden files,
+  # include_hidden: false
+
+  # Label for the column.
+  #
+  # label (optional):
+
+  # Maximum width of the column. Overrides the value at `grid.max_name_width`.
+  #
+  # max_name_width:
+
+  # List of matchers for files to include in the column. The file is included in
+  # the column is any of the matchers is successful.
+  #
+  # Valid matchers:
+  #
+  #  - any                  Matches any file
+  #  - all: []              Matches a file if all matchers are successful.
+  #  - changes: "git"       Matches a file if it has changes since the last
+  #                         commit in a Git repository.
+  #  - changes: "duration"  Matches a file if it has modified in the time
+  #                         specified by "duration"
+  #  - glob: []             Matches using a pattern or a list of patterns.
+  #  - mime: "type"         Matches by MIME types (according to file name
+  #                         extension).
+  #  - regex: "re"          Matches a file name against a regular expression.
+  #  - type: "type"         Matches by file type. "type" can be any of blockdev,
+  #                         chardev, directory, executable, file, fifo, socket,
+  #                         or symlink.
+  #
+  # matchers: []
+
+  # Filters to exclude files from this column. Use the same options from the
+  # `matchers` key.
+  #
+  # exclude: []
+
+  # Styles to apply to all files in this column.
+  #
+  # color:
+
+  # If `true`, files with changes in the Git repository will appear before other
+  # files.
+  #
+  # git_changes_first: true
+
+  # Indicates how to sort rows in this column. The first word is the sort key,
+  # which can be one of name, size, modification_time, or version. The second
+  # (optional) word can be either "asc" or "desc".
+  #
+  # sort: "name asc"
+
+# info:
+  # Content for the left side of the header. Can be a single string, or ab
+  # object with `text` and `color` fields.
+  #
+  # The following specifiers can be used in the content:
+  #
+  #    %%      Literal '%'.
+  #    %P      Path.
+  #    %S      Disk usage.
+  #    %+      Added lines (from git diff).
+  #    %-      Deleted lines (from git diff).
+  #    %C{…}   Color.
+  #    %V{…}   Variable.
+  #
+  # left:
+
+  # Like the `left` field, but for the right side of the header.
+  #
+  # right:
+
+  # Like `left`, but adding the content as an extra column.
+  #
+  # column:
+
+  # A map to define variables to be used with %V{…}. Every variable defines a
+  # list of matchers, and its value is the number of files that match any of the
+  # matchers.
+  #
+  # variables:
+
+# colors:
+  # Coloring: auto, always, never.
+  # when: auto
+
+  # `true` if $LS_COLORS should be used to define colors for files.
+  #
+  # If its value is a string, it defines the environment variable to read.
+  # use_lscolors: true
+
+  # Style for the column labels.
+  # column_label: bold
+
+  # Style for the ellipsis printed when a file name is truncated.
+  # name_ellipsis: red
+
+  # Style for the "+X entries" row when a column is truncated.
+  # more_entries: italic
+
+  # Style for the number of added lines to a file.
+  # diff_added: green
+
+  # Style for the number of deleted lines to a file.
+  # diff_deleted: red
+
+  # List of styles for file patterns.
+  # styles:
+  #   - matchers: []
+  #     color: (optional) ""
+  #     indicator: (optional)
+  #       text:
+  #       color:
+
+  # List of file paths to load more styles.
+  # style_files: []
+
+# grid:
+  # Maximum number of rows for any column. If a column contains more rows, its
+  # content is truncated.
+  # max_rows: 1
+
+  # Maximum width (in terminal columns) for the file names. If a file name
+  # exceeds this width, it is truncated.
+  # max_name_width: 1
+
+  # Spaces between each column.
+  # column_padding: 4
+
+# collector:
+  # `true` if Summer must compute the disk used by subdirectories.
+  # disk_usage: true
+
+  # `true` if Summer must read diff stats from git.
+  # git_diff: true
+
+  # Timeout for the collector processes.
+  # timeout: 500 ms