From 010ed1015d284c0cca3cfef331e3902cd8c7b885 Mon Sep 17 00:00:00 2001 From: zerone0x Date: Sat, 14 Mar 2026 03:36:39 +0100 Subject: [PATCH] docs: clarify inheritance of global defaults Fixes #1155 Co-Authored-By: Dominik Jain Co-Authored-By: Claude --- docs/02-usage/040_workflow.md | 7 ++++++- docs/02-usage/050_configuration.md | 3 +++ src/serena/resources/project.template.yml | 7 +++++-- 3 files changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/02-usage/040_workflow.md b/docs/02-usage/040_workflow.md index a4be275b..f8b3603f 100644 --- a/docs/02-usage/040_workflow.md +++ b/docs/02-usage/040_workflow.md @@ -57,7 +57,12 @@ The file allows you to configure ... * the set of tools and modes to use by default For detailed information on the parameters and possible settings, see the -[template file](https://github.com/oraios/serena/blob/main/src/serena/resources/project.template.yml). +[template file](https://github.com/oraios/serena/blob/main/src/serena/resources/project.template.yml). + +:::{note} +Many settings in project.yml *extend* or *override* settings in the global configuration file `serena_config.yml`. +So use the project configuration specifically for aspects that apply only to the particular project. +::: **Local Overrides**. The project.yml file is intended to be versioned together with the project. You can specify local overrides for the settings in a `project.local.yml` file in the same directory diff --git a/docs/02-usage/050_configuration.md b/docs/02-usage/050_configuration.md index 0c64233e..3a1598f3 100644 --- a/docs/02-usage/050_configuration.md +++ b/docs/02-usage/050_configuration.md @@ -33,6 +33,9 @@ Some of the configurable settings include: * logging settings * advanced settings specific to individual language servers (see [below](ls-specific-settings)) +The global configuration settings apply to all projects. +Some of the settings it contains can, however, be *extended* or *overridden* in project-specific settings, contexts and modes. + For detailed information on the parameters and possible settings, see the [template file](https://github.com/oraios/serena/blob/main/src/serena/resources/serena_config.template.yml). diff --git a/src/serena/resources/project.template.yml b/src/serena/resources/project.template.yml index b5b55d86..78fea480 100644 --- a/src/serena/resources/project.template.yml +++ b/src/serena/resources/project.template.yml @@ -56,7 +56,9 @@ ignored_paths: [] # Added on 2025-04-18 read_only: false -# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details. +# list of tool names to exclude. +# This extends the existing exclusions (e.g. from the global configuration) +# # Below is the complete list of tools for convenience. # To make sure you have the latest list of tools, and to view their descriptions, # execute `uv run scripts/print_tool_overview.py`. @@ -97,7 +99,8 @@ read_only: false # * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store. excluded_tools: [] -# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default) +# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default). +# This extends the existing inclusions (e.g. from the global configuration). included_optional_tools: [] # fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.