Add pytask lock command

Author: tobiasraabe

docs/source/_static/md/commands/build-options.md

@@ -2,7 +2,6 @@
 | ---------------------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
 | <code>-c, --config FILE</code>                             | -                                                                         | Path to configuration file.                                                                                                                   |
 | <code>--capture [fd\|no\|sys\|tee-sys]</code>              | <code>fd</code>                                                           | Per task capturing method.                                                                                                                    |
-| <code>--clean-lockfile</code>                              | <code>false</code>                                                        | Rewrite the lockfile with only currently collected tasks.                                                                                     |
 | <code>--database-url TEXT</code>                           | -                                                                         | Url to the database.                                                                                                                          |
 | <code>--debug-pytask</code>                                | <code>false</code>                                                        | Trace all function calls in the plugin framework.                                                                                             |
 | <code>--disable-warnings</code>                            | <code>false</code>                                                        | Disables the summary for warnings.                                                                                                            |

docs/source/_static/md/commands/command-list.md

@@ -4,5 +4,6 @@
 | [`clean`](clean.md)     | Clean the provided paths by removing files unknown to pytask. |
 | [`collect`](collect.md) | Collect tasks and report information about them.              |
 | [`dag`](dag.md)         | Create a visualization of the directed acyclic graph.         |
+| [`lock`](lock.md)       | Inspect and update recorded task state in the lockfile.       |
 | [`markers`](markers.md) | Show all registered markers.                                  |
 | [`profile`](profile.md) | Show information about resource consumption.                  |

docs/source/how_to_guides/portability.md

@@ -85,11 +85,11 @@ tasks run. If tasks are removed or renamed, their old entries remain as stale da
 are ignored.
 
 To clean up stale entries without deleting the file, run
-[`pytask build --clean-lockfile`](../reference_guides/commands.md#pytask-build--clean-lockfile):
+[`pytask lock clean`](../reference_guides/commands.md#pytask-lock-clean):
 
 ```console
-$ pytask build --clean-lockfile
+$ pytask lock clean
 ```
 
-This rewrites the lockfile after a successful build with only the currently collected
-tasks and their current state values.
+This rewrites the lockfile with only the currently collected tasks and their current
+state values.

docs/source/reference_guides/lockfile.md

@@ -51,9 +51,9 @@ There are two portability concerns:
 
 ## Maintenance
 
-Use [`pytask build --clean-lockfile`](commands.md#pytask-build--clean-lockfile) to
-rewrite `pytask.lock` with only currently collected tasks. The rewrite happens after a
-successful build and recomputes current state values without executing tasks again.
+Use [`pytask lock clean`](commands.md#pytask-lock-clean) to rewrite `pytask.lock` with
+only currently collected tasks. The command removes stale task entries without executing
+tasks again.
 
 ## File Format Reference
 

src/_pytask/build.py

@@ -72,7 +72,6 @@ def build(  # noqa: PLR0913
     debug_pytask: bool = False,
     disable_warnings: bool = False,
     dry_run: bool = False,
-    clean_lockfile: bool = False,
     editor_url_scheme: Literal["no_link", "file", "vscode", "pycharm"]  # noqa: PYI051
     | str = "file",
     explain: bool = False,
@@ -132,8 +131,6 @@ def build(  # noqa: PLR0913
         Whether warnings should be disabled and not displayed.
     dry_run : bool, default=False
         Whether a dry-run should be performed that shows which tasks need to be rerun.
-    clean_lockfile : bool, default=False
-        Whether the lockfile should be rewritten to only include collected tasks.
     editor_url_scheme : Literal["no_link", "file", "vscode", "pycharm"] | str
         A URL scheme that allows task, node, and file names to become clickable links.
     explain : bool, default=False
@@ -228,7 +225,6 @@ def build(  # noqa: PLR0913
             "debug_pytask": debug_pytask,
             "disable_warnings": disable_warnings,
             "dry_run": dry_run,
-            "clean_lockfile": clean_lockfile,
             "editor_url_scheme": editor_url_scheme,
             "explain": explain,
             "expression": expression,
@@ -357,12 +353,6 @@ def build(  # noqa: PLR0913
     default=False,
     help="Execute a task even if it succeeded successfully before.",
 )
-@click.option(
-    "--clean-lockfile",
-    is_flag=True,
-    default=False,
-    help="Rewrite the lockfile with only currently collected tasks.",
-)
 @click.option(
     "--explain",
     is_flag=True,