From 3721483c2dbdd01ec6cbc6ba86ca84f8d7c2859a Mon Sep 17 00:00:00 2001
From: Sebastian Kuzminsky <seb@highlab.com>
Date: Sat, 12 Jul 2025 14:48:04 -0600
Subject: [PATCH 1/2] git::sync(): more helpful error message when merge fails

---
 src/git.rs | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/git.rs b/src/git.rs
index 63cb004..fe0446a 100644
--- a/src/git.rs
+++ b/src/git.rs
@@ -251,7 +251,7 @@ pub fn sync(dir: &std::path::Path, remote: &str, branch: &str) -> Result<(), Git
     if !result.status.success() {
         println!(
             "Sync failed!  'git log' error!  Help, a human needs to fix the mess in {:?}",
-            dir
+            branch
         );
         println!("stdout: {}", std::str::from_utf8(&result.stdout).unwrap());
         println!("stderr: {}", std::str::from_utf8(&result.stderr).unwrap());
@@ -277,7 +277,7 @@ pub fn sync(dir: &std::path::Path, remote: &str, branch: &str) -> Result<(), Git
     if !result.status.success() {
         println!(
             "Sync failed!  'git log' error!  Help, a human needs to fix the mess in {:?}",
-            dir
+            branch
         );
         println!("stdout: {}", std::str::from_utf8(&result.stdout).unwrap());
         println!("stderr: {}", std::str::from_utf8(&result.stderr).unwrap());
@@ -297,7 +297,7 @@ pub fn sync(dir: &std::path::Path, remote: &str, branch: &str) -> Result<(), Git
     if !result.status.success() {
         println!(
             "Sync failed!  Merge error!  Help, a human needs to fix the mess in {:?}",
-            dir
+            branch
         );
         println!("stdout: {}", std::str::from_utf8(&result.stdout).unwrap());
         println!("stderr: {}", std::str::from_utf8(&result.stderr).unwrap());
@@ -312,7 +312,7 @@ pub fn sync(dir: &std::path::Path, remote: &str, branch: &str) -> Result<(), Git
     if !result.status.success() {
         println!(
             "Sync failed!  Push error!  Help, a human needs to fix the mess in {:?}",
-            dir
+            branch
         );
         println!("stdout: {}", std::str::from_utf8(&result.stdout).unwrap());
         println!("stderr: {}", std::str::from_utf8(&result.stderr).unwrap());
-- 
2.47.3


From 8d5105e4d5183e8cd3a826d69bd2369c8f218cc8 Mon Sep 17 00:00:00 2001
From: Sebastian Kuzminsky <seb@highlab.com>
Date: Sat, 12 Jul 2025 14:54:23 -0600
Subject: [PATCH 2/2] flesh out the README some

---
 README.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 81 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 3ca1a4e..71a2f8e 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,81 @@
-This is a distributed, collaborative bug tracker, backed by git.
+Entomologist is a distributed, collaborative, offline-first issue tracker,
+backed by git.
+
+
+# Quick start
+
+Entomologist provides a single executable called `ent` which performs
+all interaction with the issues database.  `ent --help` provides terse
+usage info.
+
+No initialization is needed, just start using `ent` inside your git repo:
+
+```
+$ git clone git@server:my-repo.git
+$ cd my-repo
+$ ent list
+# no issues shown, unless my-repo contained some already
+```
+
+Create an issue:
+```
+$ ent new
+# Starts your $EDITOR.  Type in the issue description, "git-commit
+# style" with a title line, optionally followed by an empty line and
+# free form text.
+```
+
+List issues with `ent list`.  Optionally takes a filter argument that
+controls which issues are shown, see `ent list --help` for details.
+For example, to show only new and backlog issues assigned to me or
+unassigned, run `ent list state=new,backlog:assignee=$(whoami),`.
+
+Show all details of an issue with `ent show`.
+
+Modify the state of an issue using `ent state`.  Supported states are New,
+Backlog, InProgress, Done, and WontDo.
+
+Assign an issue to a person using `ent assign`.  The person is just
+a free-form text field for now.  Make it a name, or an email address,
+or whatever you want.
+
+Add a comment on an issue with `ent comment`.
+
+Edit an issue or a comment with `ent edit`.
+
+Add or remove tags on an issue using `ent tag`.
+
+
+# Synchronization
+
+Synchronize your local issue database with the server using `ent sync`.
+This will:
+
+1. Fetch the remote issue database branch into your local repo.
+
+2. Show the list of local changes not yet on the remote.
+
+3. Show the list of remote changes not yet incorporated into the local
+   branch.
+
+4. Merge the branches.
+
+5. Push the result back to the remote.
+
+Step 4 might fail if (for example) both sides edited the same issue in
+a way that git can't merge automatically.  In this case, check out the
+`entomologist-data` branch, merge by hand and resolve the conflicts,
+and run `ent sync` again.
+
+
+# Git storage
+
+Issues are stored in a normal orphan branch in a git repo, next to but
+independent of whatever else is stored in the repo.  The default branch
+name is `entomologist-data`.
+
+Anyone who has a clone of the repo has the complete issue database.
+
+Anyone who has write-access to the repo can modify the issue database.
+The issue database branch can be modified by pull request, same as any
+other branch.
-- 
2.47.3