Update to 3.0.0-rc.1 (#155)

- Update to the first v3 RC
- Publish v3 docs with a disclaimer at the top
- Fix issue where gfold would not continue execution with an empty
  config file

Signed-off-by: Nick Gerace <[email protected]>

CHANGELOG.md

@@ -24,6 +24,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - Codebase to a domain-driven architecture (major refactor)
 
+### Removed
+
+- Mention of the [deprecated, old Homebrew tap](https://github.com/nickgerace/homebrew-gfold) in the README
+- Short `-h` flag due to CLI crate addition (`argh`)
+
 ### Notes
 
 - Evaluated using `tracing` and `tracing-subscriber` over `log` and `env_logger`, but due to their combined larger size, the logging crates remain the same as before.

Cargo.toml

@@ -10,7 +10,7 @@ readme = "README.md"
 repository = "https://github.com/nickgerace/gfold/"
 
 edition = "2021"
-version = "2.0.2"
+version = "3.0.0-rc.1"
 
 [dependencies]
 anyhow = "1"

Makefile

@@ -4,21 +4,24 @@ INSTALLED := $(shell which gfold)
 
 .DEFAULT_GOAL := prepare
 
-prepare: fmt
+prepare:
+	cd $(MAKEPATH); cargo +nightly fmt
 	cd $(MAKEPATH); cargo update
 	cd $(MAKEPATH); cargo fix --edition-idioms --allow-dirty --allow-staged
 	cd $(MAKEPATH); cargo clippy --all-features --all-targets
 .PHONY: prepare
 
-fmt:
-	cd $(MAKEPATH); cargo +nightly fmt
-.PHONY: fmt
+ci: lint test
+.PHONY: ci
 
-ci:
+test:
+	cd $(MAKEPATH); cargo test -- --nocapture
+.PHONY: test
+
+lint:
 	cd $(MAKEPATH); cargo +nightly fmt --all -- --check
 	cd $(MAKEPATH); cargo clippy -- -D warnings
-	cd $(MAKEPATH); cargo test -- --nocapture
-.PHONY: ci
+.PHONY: lint
 
 release:
 	cd $(MAKEPATH); cargo build --release

README.md

@@ -5,26 +5,57 @@
 [![build](https://img.shields.io/github/workflow/status/nickgerace/gfold/merge/main?style=flat-square)](https://github.com/nickgerace/gfold/actions?query=workflow%3Amerge+branch%3Amain)
 [![license](https://img.shields.io/github/license/nickgerace/gfold?style=flat-square&color=purple)](./LICENSE)
 
+> This **README** is for `gfold 3.x` users.
+> Since `gfold 3.x` has not yet been released, contents of this **README** may be inapplicable to your version of `gfold`.
+>
+> For the latest, full release of `gfold 2.x`, please refer to the [**README** corresponding to the latest, full release](https://github.com/nickgerace/gfold/blob/2.0.2/README.md).
+
 `gfold` is a CLI-driven application that helps you keep track of multiple Git repositories.
 
 ```
 % gfold
+📡 astrid ⇒ /home/neloth/src/astrid
+unclean (main)
+[email protected]:db/astrid.git
+[email protected]
+
+📡 fev ⇒ /home/neloth/src/fev
+bare (issue2277)
+none
+[email protected]
+
+📡 gb ⇒ /home/neloth/src/gb
+unpushed (dev)
+https://github.com/hrothgar/gb.git
+[email protected]
+
+📡 pam ⇒ /home/neloth/src/pam
+clean (main)
+https://github.com/onc/pam.git
+[email protected]
+```
+
+The classic display mode can be toggled on with `--classic`.
+
+```
+% gfold --classic
 astrid  unclean   main       [email protected]:db/astrid.git
-fev     bare      main       https://github.com/institute/fev.git
+fev     bare      main       none
 gb      unpushed  dev        https://github.com/hrothgar/gb.git
 neloth  unclean   patch      [email protected]:telvanni/neloth.git
 pam     clean     main       https://github.com/onc/pam.git
 prime   clean     issue2287  [email protected]:bos/prime.git
 ```
 
+If you'd prefer to use the classic display mode by default, and avoid setting the flag every time, you can set it in the config file (see **Usage** section).
+
 ## Description
 
 This app displays relevant information for multiple Git repositories in one to many directories.
 While this tool might seem limited in scope and purpose, that is by design.
 
-It prints each repository in alphabetical order, and pads each result based on the longest directory, branch, and status string.
 By default, `gfold` looks at every Git repository via traversal from the current working directory.
-However, if you would like to target another directory, you can pass that path (relative or absolute) as the first argument.
+However, if you would like to target another directory, you can pass that path (relative or absolute) as the first argument or change the default path in the config file.
 
 ## Installation
 
@@ -38,9 +69,7 @@ You can use [Homebrew](https://brew.sh) to install the [tap](https://github.com/
 brew install nickgerace/nickgerace/gfold
 ```
 
-The original [tap](https://github.com/nickgerace/homebrew-gfold) will no longer be maintained after version `2.0.1`.
-Please migrate to the new tap using the command above.
-Neither the current and deprecated taps will work with [Linuxbrew](https://docs.brew.sh/Homebrew-on-Linux).
+**Please note:** the tap may not work with [Linuxbrew](https://docs.brew.sh/Homebrew-on-Linux).
 
 ### AUR
 
@@ -78,18 +107,22 @@ If you do not want to use one of the above installation methods, you can downloa
 curl https://raw.githubusercontent.com/nickgerace/gfold/main/scripts/install.sh | bash
 ```
 
-For security, please note that the installation convenience script does not verify the binary with a checksum.
-Discretion is advised, including downloading and reading the script before execution.
-
 To uninstall `gfold` fully, after using this installation method, execute the following script:
 
 ```bash
 curl https://raw.githubusercontent.com/nickgerace/gfold/main/scripts/uninstall.sh | bash
 ```
 
+The uninstall script can also be used for cleanup in the event of a failed install.
+
+#### Security Considerations
+
+Please note that the installation convenience script _does not verify the binary with a checksum_.
+Discretion is advised, including downloading and reading the script before execution.
+
 ## Usage
 
-Pass in the `-h`, or `--help`, flag to see all the options for using this application.
+Pass in `--help` flag to see all the options for using this application.
 
 ```bash
 gfold
@@ -100,6 +133,51 @@ gfold /this/is/an/absolute/path
 gfold ../../this/is/a/relative/path
 ```
 
+### Config File
+
+Upon execution, `gfold` will look for a config file at the following path on macOS, Linux and similar operating systems:
+
+```bash
+$HOME/.config/gfold/gfold.json
+```
+
+On Windows, the config file is located at the following path:
+
+```powershell
+{FOLDERID_Profile}\.config\gfold\gfold.json
+```
+
+Creating and using the config file is entirely optional, and you can ignore your config file at any time using the `-i` flag.
+
+#### Example: Creating a Config File
+
+Here is an example creation workflow for a config file.
+This config file will default to the classic display mode and set the default path to `$HOME`, rather than the current working directory.
+
+```bash
+gfold --classic ~/ --print > $HOME/.config/gfold/gfold.json
+```
+
+Here are the contents of the resulting config file:
+
+```json
+{
+  "path": "/home/neloth",
+  "display_mode": "Classic"
+}
+```
+
+#### Example: Backing Up a Config file
+
+You can back up a config file and track its history with `git`.
+On macOS, Linux, and most systems, you can link the file back to a `git` repository.
+
+```bash
+ln -s path/to/repository/gfold.json $HOME/.config/gfold/gfold.json
+```
+
+Now, you can update the config file within your repository and include the linking as part of your environment setup workflow.
+
 ## Compatibility
 
 `gfold` is intended to be ran on *any* tier one Rust 🦀 target that `git` is also available on.

RELEASE.md

@@ -7,7 +7,7 @@ This document contains all information related to release.
 This checklist details the `gfold` release process.
 Steps should (and frequently must) be executed in sequential order.
 
-- [ ] Checkout and rebase `main` to its latest commit
+- [ ] Checkout and rebase `main` to its latest commit, then checkout a new branch
 - [ ] Change the `version` field in `Cargo.toml` to the new tag
 - [ ] **Full Releases Only**: change the version in `CHANGELOG.md` and uncomment the following line: `<!--The latest version contains all changes.-->`
 - [ ] Run final `make` targets and verify that everything looks/works as expected:
@@ -16,15 +16,15 @@ Steps should (and frequently must) be executed in sequential order.
 make ci build
 ```
 
-- [ ] Create and _do not push/merge_ a commit with the following message: `Update to <tag>`
+- [ ] Create and _do not merge_ a commit with the following message: `Update to <tag>`
 
 - [ ] Test and verify the publishing workflow:
 
 ```bash
 cargo publish --dry-run
 ```
 
-- [ ] Push/merge the preparation commit into `main`
+- [ ] Merge the preparation commit into `main`
 - [ ] Checkout and rebase `main` to its latest commit, which should be the aforementioned commit
 - [ ] Tag and push the tag:
 

src/config.rs

@@ -1,5 +1,5 @@
 use crate::error::Error;
-use anyhow::Result;
+use anyhow::{Context, Result};
 use log::warn;
 use serde::{Deserialize, Serialize};
 use std::env;
@@ -46,13 +46,21 @@ impl Config {
     // This method tries to deserialize the config file (empty, non-existent, partial or complete)
     // and uses "EntryConfig" as an intermediary struct. This is the primary method used when
     // creating a config.
+    //
+    // Within this method, we check if the config file is empty before deserializing it. Users
+    // should be able to proceed with empty config files. If empty, then we fall back to the
+    // "EntryConfig" default before conversion.
     pub fn try_config() -> Result<Config> {
         let home = dirs::home_dir().ok_or(Error::HomeDirNotFound)?;
         let entry_config = match File::open(home.join(".config").join("gfold").join("gfold.json")) {
-            Ok(o) => {
-                let reader = BufReader::new(o);
-                serde_json::from_reader(reader)?
-            }
+            Ok(o) => match o.metadata()?.len() {
+                len if len > 0 => {
+                    let reader = BufReader::new(o);
+                    serde_json::from_reader(reader)
+                        .context("config file's contents are likely invalid JSON")?
+                }
+                _ => EntryConfig::default(),
+            },
             Err(e) => {
                 warn!("{}", e);
                 EntryConfig::default()