Some updates for the cherry farmer tool (#136)

kb/tooling/index.md

@@ -4,5 +4,6 @@ This section is about the custom tooling available in this repo.
 
 - [task commands](task_commands.md) - a set of (`make`-like) shortcuts for various commands and scripts for repository management, development, testing, etc.
 - tools from `terrarium` ([README](../../terrarium/README.md)):
-  - [dl-git](../../terrarium/dl_gitmanager/README.md) - a wrapper for advanced git commands, for usage mainly in the CI workflow
+  - [dl-git / dl-cherry-farmer](../../terrarium/dl_gitmanager/README.md) - a wrapper for advanced git commands, for usage mainly in the CI workflow
+    and a tool for managing info on cherry-picked commits in a repo
   - [dl-repo / dl-package](../../terrarium/dl_repmanager/README.md) - tools for managing and inspecting packages, their dependencies, meta-packages, etc.

terrarium/dl_gitmanager/README.md

@@ -121,27 +121,46 @@ dl-cherry-farmer show --src-branch <branch> --dst-branch <branch> --all
 ```
 
 Here `--src-branch` and `--dst-branch` are the names of the branches that you want to compare
-With `--new` new (not picked and not ignored commits) will be shown.
-With `--picked` picked commits will be shown.
-With `--ignored` ignored commits will be shown.
-With `-a` or `--all` all commits will be shown.
+
+Several options control which commits to show:
+- `--new`: new (not picked and not ignored commits) will be shown.
+- `--picked`: picked commits will be shown.
+- `--ignored`: ignored commits will be shown.
+- `-a` or `--all`: all commits will be shown.
+
+If none of these is specified, then `--new` is assumed.
+
 
 ### iter
 
 Iterate over all commits in diff and pick or ignore them interactively
 
 ```bash
 dl-cherry-farmer show --src-branch <branch> --dst-branch <branch>
-dl-cherry-farmer show --src-branch <branch> --dst-branch <branch> --all
+dl-cherry-farmer show --src-branch <branch> --dst-branch <branch> --new
+dl-cherry-farmer show --src-branch <branch> --dst-branch <branch> --one
 ```
 
-All options are the same as for the `show` command.
+Accepts the same options as does the `show` command, but has some additional ones:
+- `--one`: instead of iterating over all commits show just one and quit after it is handled.
+
+The tool will ask for a new state and message for each commit.
+If the message is not specified, a default one will be generated.
+
+To skip an un-picked commit (and not mark it as `ignored` or `picked`) use the state `new`.
+
 
 ### mark
 
+Non-interactive command for marking commits.
+
 ```bash
-dl-cherry-farmer mark --commit <commit_id> --state <state>
+dl-cherry-farmer mark --commit <commit> --state <state>
+dl-cherry-farmer mark --commit <commit> --state <state> -m <message>
+dl-cherry-farmer mark --commit <commit> --state <state> --message <message>
 ```
 
-Here `commid_id` should be a valid commit ID, and `state` is the state to be set for this commit.
+Here `commit` should be a valid commit ID, and `state` is the state to be set for this commit.
 If `--state new` is specified, then the info about this commit is simply deleted from the saved state.
+Use `-m` or `--message` to specify a pick message (will be saved in the state file).
+If the message is not specified, a default one will be generated.

terrarium/dl_gitmanager/dl_gitmanager/cherry_farmer.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from contextlib import contextmanager
+import datetime
 from enum import (
     Enum,
     unique,
@@ -177,6 +178,8 @@ def mark(
         message: Optional[str] = None,
         timestamp: Optional[int] = None,
     ) -> None:
+        if message == "":
+            message = f"Set to state {state.name!r} at {datetime.datetime.utcnow().isoformat()}"
         self._state.mark(commit_id=commit_id, state=state, message=message, timestamp=timestamp)
 
     def search_pick_suggestion(

terrarium/dl_gitmanager/dl_gitmanager/scripts/cherry_farmer_cli.py

@@ -61,7 +61,7 @@ def get_parser(cls) -> argparse.ArgumentParser:
         commit_parser.add_argument("--commit", help="Commit ID", required=True)
 
         message_parser = argparse.ArgumentParser(add_help=False)
-        message_parser.add_argument("-m", "--message", help="Message")
+        message_parser.add_argument("-m", "--message", help="Message", default="")
 
         state_parser = argparse.ArgumentParser(add_help=False)
         state_parser.add_argument(
@@ -96,16 +96,19 @@ def get_parser(cls) -> argparse.ArgumentParser:
             parents=[src_dst_branch_parser, commit_type_flag_parser],
             help="List file paths with changes given as commit range",
         )
+
         subparsers.add_parser(
             "mark",
             parents=[commit_parser, state_parser, message_parser],
             help="Mark commit as picked/ignored/new",
         )
-        subparsers.add_parser(
+
+        iter_parser = subparsers.add_parser(
             "iter",
             parents=[src_dst_branch_parser, commit_type_flag_parser],
             help="Iterate over commits and pick them interactively",
         )
+        iter_parser.add_argument("--one", action="store_true", help="Show only one commit and quit after handling it.")
 
         return parser
 
@@ -120,7 +123,7 @@ def _get_states(self, picked: bool, ignored: bool, new: bool, all: bool) -> set[
 
         if not result:
             # no flags means "all"
-            return self._get_states(all=True)
+            return self._get_states(new=True)
 
         return result
 
@@ -187,7 +190,14 @@ def _prompt_mark_commit(self, commit_state_item: CommitRuntimeStateItem) -> tupl
         return state, message
 
     def iter_(
-        self, src_branch: str, dst_branch: Optional[str], picked: bool, ignored: bool, new: bool, all: bool
+        self,
+        src_branch: str,
+        dst_branch: Optional[str],
+        picked: bool,
+        ignored: bool,
+        new: bool,
+        all: bool,
+        one: bool,
     ) -> None:
         states = self._get_states(picked=picked, ignored=ignored, new=new, all=all)
         for commit_state_item in self.cherry_farmer.iter_diff_commits(
@@ -214,6 +224,9 @@ def iter_(
                 message=message,
                 timestamp=commit_state_item.saved_state.timestamp,
             )
+            if one:
+                # quit after just one handled commit
+                break
 
     @classmethod
     def initialize(cls, cherry_farmer: CherryFarmer) -> GitManagerTool:
@@ -255,6 +268,7 @@ def run_parsed_args(cls, args: argparse.Namespace) -> None:
                         ignored=args.ignored,
                         new=args.new,
                         all=args.all,
+                        one=args.one,
                     )
                 case _:
                     raise RuntimeError(f"Got unknown command: {args.command}")