Document lockfile in tutorials

Author: tobiasraabe

docs/source/tutorials/defining_dependencies_products.md

@@ -36,6 +36,8 @@ my_project
 │       ├────task_data_preparation.py
 │       └────task_plot_data.py
 │
+├───pytask.lock
+│
 └───pyproject.toml
 ```
 
@@ -107,6 +109,10 @@ Now, let us execute the two paths.
 
 --8<-- "docs/source/_static/md/defining-dependencies-products.md"
 
+The build updates `pytask.lock` with the state of both tasks. When you run the same
+tasks again without changing their dependencies, products, or source files, pytask uses
+the lockfile to skip them.
+
 ## Relative paths
 
 Dependencies and products do not have to be absolute paths. If paths are relative, they

docs/source/tutorials/set_up_a_project.md

@@ -14,7 +14,8 @@ move to the next section of the tutorials.
 
 ## The directory structure
 
-The following directory tree gives an overview of the project's different parts.
+The following directory tree gives an overview of the project's different parts after
+the first build.
 
 ```text
 my_project
@@ -30,13 +31,16 @@ my_project
 │       ├────config.py
 │       └────...
 │
+├───pytask.lock
+│
 └───pyproject.toml
 ```
 
-Replicate this directory structure for your project or start from pytask's
+Create the project files and folders for your project or start from pytask's
 [cookiecutter-pytask-project](https://github.com/pytask-dev/cookiecutter-pytask-project)
 template or any other
 [linked template or example project](../how_to_guides/bp_templates_and_projects.md).
+pytask creates the `.pytask` folder and `pytask.lock` file during builds.
 
 ## The `src` directory
 
@@ -134,6 +138,12 @@ The `[tool.pytask.ini_options]` section tells pytask to look for tasks in
 The `.pytask` directory is where pytask stores its information. You do not need to
 interact with it.
 
+## The `pytask.lock` file
+
+The `pytask.lock` file records which tasks and products are up to date. pytask updates
+it during builds so later runs can skip unchanged tasks. This file should be kept in
+version control.
+
 ## Installation
 
 === "uv"

docs/source/tutorials/using_a_data_catalog.md

@@ -36,6 +36,8 @@ my_project
 │       ├────task_data_preparation.py
 │       └────task_plot_data.py
 │
+├───pytask.lock
+│
 └───pyproject.toml
 ```
 
@@ -148,6 +150,8 @@ my_project
 │
 ├───pyproject.toml
 │
+├───pytask.lock
+│
 ├───src
 │   └───my_project
 │       ├────config.py

docs/source/tutorials/write_a_task.md

@@ -24,6 +24,8 @@ my_project
 │       ├────config.py
 │       └────task_data_preparation.py
 │
+├───pytask.lock
+│
 └───pyproject.toml
 ```
 
@@ -78,6 +80,9 @@ Now, execute pytask to collect tasks in the current and subsequent directories.
 
 --8<-- "docs/source/_static/md/write-a-task.md"
 
+After the task succeeds, pytask writes `pytask.lock` next to `pyproject.toml`. Keep this
+file under version control so later builds can detect unchanged tasks.
+
 <a id="customize-task-names"></a>
 
 ## Customize task names