Add first shot at readme

README.md

@@ -1,29 +1,66 @@
 # GiCo
+A collection of tools for local processing of *Gi*t *Co*mmits
 
-Goals:
+Included Tools:
-1. Provide a git post-commit hook binary that allows you to track commit frequency locally
+- gico
-  - requires a lock file
+- gitfetch
-1. Save a history locally to a JSON file
+- mgfetch
-  - requires a lock file
+- svg-server
-1. Provide functionality to display the data:
+
-  - bubbletea interactive, scrollable graph
+## GiCo Core library
-  - one-shot printed graph for a date range (default 1 year)
+
-  - print out commit count
+The core library for GiCo (separate from the `gico` executable of the same
-    - today
+name) provides utilities to read in a list of directories containing git
-    - this week
+repositories and translating them into a list of day-aligned lists--each day
-    - this month
+of the year points to a list structs containing metadata on each commit created
-    - this year
+that day.
-1. Provide an import method to add old repos to history
+
-1. Expose parsing / counting functions to other libraries
+The repositories can be parsed synchronously or in parallel, using goroutines
+and channels.
+There is also a configurable caching interval to take advantage of memoization
+as an exercise in dynamic programming, which makes the library suitable for
+frequent calls such as those from a BubbleTea UI application.
+
+It is up to more concrete implementations to decide how this data is visualized
+or otherwise exposed to an end-user.
+For this reason, several example tools have been provided.
+
+## Executables
+### gico
+
+The gico binary is a tui tool that loads a list of git repos on a system
+and turns it into an interactive Github-style heatmap (coloring support
+included).
+
+By default, gico uses [mg](github.com/taigrr/mg) to pull in a central list of
+repos and parses the user's git config to extract the email and name of the
+current user.
+The GiCo library is used to load all the repos and translate them into a heatmap
+and convert the values into a dynamically scaled, user-configurable color
+pallette (see [simplecolorpalettes](github.com/taigrr/simplecolorpalettes)).
+
+A searchable settings view is available to allow users to select and deselect
+individual repos and authors to include in the graph.
+
+Example GIF:
 
 
+### gitfetch
 
-Notes:
+Like your standard fetch program, gitfetch uses the GiCo library to parse the
-- use a client-server model to make the execution of the git hook much faster (no need to load, parse, save the file every execution)
+git history of a repo in the current directory and print a gitgraph out to the
- - An appropriate communication method for an application like this would be Unix Domain Sockets, to reduce network overhead.
+terminal.
-   However, a goal of the program is to serve generated graph images over an API, so since we already need network communication for that, it makes sense to reuse it rather than listen on two interfaces at once.
-- env var PWD is set to git repo base even when in a subfolder (subfolder is kept in GIT_PREFIX)
-- Author Email is kept in  GIT_AUTHOR_EMAIL=<string>
-- Commit message file is in argv[1] for hook invocation, read in the file (and ignore empty lines + lines starting with `#` to get the message
-- use the current date for the 
 
+### mgfetch
+
+mgfetch uses [mg](github.com/taigrr/mg) to pull in a list of all git repos and
+combines the heatmap lists into a single gitgraph, and prints it to the
+terminal.`
+
+### svg-server
+
+svg-server uses GiCo in a similar way to mgfetch, by first pulling in a list of
+all repos seen by [mg](github.com/taigrr/mg) and then generates svg files
+on-the-fly depicting the resultant gitgraph.
+svg-server is suitable for embedding an svg of your gitgraph onto your desktop
+using conky, for example.