feat: added site pruning logic

.changes/unreleased/Added-20250919-155624.yaml

@@ -0,0 +1,3 @@
+kind: Added
+body: Added options for filtering of nodes as replacement for site and component targeting
+time: 2025-09-19T15:56:24.62356674+02:00

docs/src/howto/cli/filtering-commands.md

@@ -0,0 +1,28 @@
+# Filtering commands
+
+> For site-component targeting with `--filter` the deployment type of the component must be marked as `site-component`!
+
+By default, mach composer cli will run all nodes in the configuration in the order inferred from the configuration. You
+can filter which nodes to run by using one or more `--filter` flags on the commands that support it. With this you can
+more selectively target specific nodes in your configuration.
+
+The filter expression is a simple string that is matched against the node names:
+
+- Run a component: `mach-composer apply --filter component-1`
+- Run a site: `mach-composer apply --filter site-1`
+- Run a specific component in a specific site: `mach-composer apply --filter site-1/component-1`
+
+Some additional microsyntaxes are available to further define which nodes to run:
+
+- `site-1...` will run site-1 and all dependent components
+- `site-1/component-1...` will run component-1 in site-1 and all its dependencies
+
+Syntaxes can also be combined by using multiple `--filter` flags. Note that when multiple filters are provided that
+could match the same node, priority is given to the most generic filter. This means that any less generic filters are
+ignored:
+
+- Ignores `site-1/component-1` because `site-1...` already matches it:
+  `mach-composer apply --filter site-1... --filter site-1/component-1`
+
+
+

docs/src/reference/cli/mach-composer.md

@@ -18,18 +18,18 @@ MACH composer is a framework that you use to orchestrate and extend modern digit
 
 ### SEE ALSO
 
-* [mach-composer apply](mach-composer_apply.md)	 - Apply the configuration.
+* [mach-composer apply](mach-composer_apply.md)	 - Apply the configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 * [mach-composer cloud](mach-composer_cloud.md)	 - Manage your Mach Composer Cloud
 * [mach-composer components](mach-composer_components.md)	 - List all components.
 * [mach-composer generate](mach-composer_generate.md)	 - Generate the Terraform files.
 * [mach-composer graph](mach-composer_graph.md)	 - Print the execution graph for this project
-* [mach-composer init](mach-composer_init.md)	 - Initialize site directories Terraform files.
-* [mach-composer plan](mach-composer_plan.md)	 - Plan the configuration.
+* [mach-composer init](mach-composer_init.md)	 - Initialize site directories Terraform files. See [the documentation](/howto/cli/filtering-commands) for filtering options.
+* [mach-composer plan](mach-composer_plan.md)	 - Plan the configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 * [mach-composer schema](mach-composer_schema.md)	 - Generate a JSON schema for your config based on the plugins.
-* [mach-composer show-plan](mach-composer_show-plan.md)	 - Show the planned configuration.
+* [mach-composer show-plan](mach-composer_show-plan.md)	 - Show the planned configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 * [mach-composer sites](mach-composer_sites.md)	 - List all sites.
-* [mach-composer terraform](mach-composer_terraform.md)	 - Execute terraform commands directly
+* [mach-composer terraform](mach-composer_terraform.md)	 - Execute terraform commands directly. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 * [mach-composer update](mach-composer_update.md)	 - Update all (or a given) component.
-* [mach-composer validate](mach-composer_validate.md)	 - Validate the generated terraform configuration.
+* [mach-composer validate](mach-composer_validate.md)	 - Validate the generated terraform configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 * [mach-composer version](mach-composer_version.md)	 - Return version information of the mach-composer cli
 

docs/src/reference/cli/mach-composer_apply.md

@@ -1,6 +1,6 @@
 ## mach-composer apply
 
-Apply the configuration.
+Apply the configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 
 ```
 mach-composer apply [flags]
@@ -14,6 +14,7 @@ mach-composer apply [flags]
   -c, --component stringArray     
       --destroy                   Destroy option is a convenient way to destroy all remote objects managed by this mach config
   -f, --file string               YAML file to parse. (default "main.yml")
+      --filter stringArray        Run only nodes matching the filter expression
       --force-init                Force terraform initialization. By default mach-composer will reuse existing terraform resources
   -g, --github                    Whether logs should be decorated with github-specific formatting
   -h, --help                      help for apply

docs/src/reference/cli/mach-composer_init.md

@@ -1,6 +1,6 @@
 ## mach-composer init
 
-Initialize site directories Terraform files.
+Initialize site directories Terraform files. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 
 ```
 mach-composer init [flags]
@@ -11,6 +11,7 @@ mach-composer init [flags]
 ```
   -b, --buffer               Whether logs should be buffered and printed at the end of the run
   -f, --file string          YAML file to parse. (default "main.yml")
+      --filter stringArray   Run only nodes matching the filter expression
   -g, --github               Whether logs should be decorated with github-specific formatting
   -h, --help                 help for init
       --ignore-version       Skip MACH composer version check

docs/src/reference/cli/mach-composer_plan.md

@@ -1,6 +1,6 @@
 ## mach-composer plan
 
-Plan the configuration.
+Plan the configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 
 ```
 mach-composer plan [flags]
@@ -12,6 +12,7 @@ mach-composer plan [flags]
   -b, --buffer                    Whether logs should be buffered and printed at the end of the run
   -c, --component stringArray     
   -f, --file string               YAML file to parse. (default "main.yml")
+      --filter stringArray        Run only nodes matching the filter expression
       --force-init                Force terraform initialization. By default mach-composer will reuse existing terraform resources
   -g, --github                    Whether logs should be decorated with github-specific formatting
   -h, --help                      help for plan

docs/src/reference/cli/mach-composer_show-plan.md

@@ -1,6 +1,6 @@
 ## mach-composer show-plan
 
-Show the planned configuration.
+Show the planned configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 
 ```
 mach-composer show-plan [flags]
@@ -11,6 +11,7 @@ mach-composer show-plan [flags]
 ```
   -b, --buffer                    Whether logs should be buffered and printed at the end of the run
   -f, --file string               YAML file to parse. (default "main.yml")
+      --filter stringArray        Run only nodes matching the filter expression.
       --force-init                Force terraform initialization. By default mach-composer will reuse existing terraform resources
   -g, --github                    Whether logs should be decorated with github-specific formatting
   -h, --help                      help for show-plan

docs/src/reference/cli/mach-composer_terraform.md

@@ -1,6 +1,6 @@
 ## mach-composer terraform
 
-Execute terraform commands directly
+Execute terraform commands directly. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 
 ```
 mach-composer terraform [flags]
@@ -11,6 +11,7 @@ mach-composer terraform [flags]
 ```
   -b, --buffer                    Whether logs should be buffered and printed at the end of the run
   -f, --file string               YAML file to parse. (default "main.yml")
+      --filter stringArray        Run only nodes matching the filter expression
   -g, --github                    Whether logs should be decorated with github-specific formatting
   -h, --help                      help for terraform
       --ignore-change-detection   Ignore change detection to run even if the components are considered up to date. Per default the proxy will ignore change detection (default true)

docs/src/reference/cli/mach-composer_validate.md

@@ -1,6 +1,6 @@
 ## mach-composer validate
 
-Validate the generated terraform configuration.
+Validate the generated terraform configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 
 ### Synopsis
 
@@ -19,6 +19,7 @@ mach-composer validate [flags]
 ```
   -b, --buffer                   Whether logs should be buffered and printed at the end of the run
   -f, --file string              YAML file to parse. (default "main.yml")
+      --filter stringArray       Run only nodes matching the filter expression
   -g, --github                   Whether logs should be decorated with github-specific formatting
   -h, --help                     help for validate
       --ignore-version           Skip MACH composer version check

internal/cmd/apply.go

@@ -18,13 +18,14 @@ var applyFlags struct {
 	github                bool
 	bufferLogs            bool
 	components            []string
+	filters               []string
 	numWorkers            int
 	ignoreChangeDetection bool
 }
 
 var applyCmd = &cobra.Command{
 	Use:   "apply",
-	Short: "Apply the configuration.",
+	Short: "Apply the configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.",
 	PreRun: func(cmd *cobra.Command, args []string) {
 		preprocessCommonFlags(cmd)
 	},
@@ -39,6 +40,7 @@ func init() {
 	applyCmd.Flags().BoolVarP(&applyFlags.forceInit, "force-init", "", false, "Force terraform initialization. By default mach-composer will reuse existing terraform resources")
 	applyCmd.Flags().BoolVarP(&applyFlags.autoApprove, "auto-approve", "", false, "Suppress a terraform init for improved speed (not recommended for production usage)")
 	applyCmd.Flags().BoolVarP(&applyFlags.destroy, "destroy", "", false, "Destroy option is a convenient way to destroy all remote objects managed by this mach config")
+	applyCmd.Flags().StringArrayVarP(&applyFlags.filters, "filter", "", nil, "Run only nodes matching the filter expression")
 	applyCmd.Flags().StringArrayVarP(&applyFlags.components, "component", "c", nil, "")
 	applyCmd.Flags().BoolVarP(&applyFlags.ignoreChangeDetection, "ignore-change-detection", "", false, "Ignore change detection to run even if the components are considered up to date")
 	applyCmd.Flags().BoolVarP(&applyFlags.github, "github", "g", false, "Whether logs should be decorated with github-specific formatting")
@@ -47,7 +49,7 @@ func init() {
 
 func applyFunc(cmd *cobra.Command, _ []string) error {
 	if len(applyFlags.components) > 0 {
-		log.Warn().Msgf("Components option not implemented")
+		log.Warn().Msgf("Component option is deprecated. Please use `--filter your-component-name instead.")
 	}
 
 	if applyFlags.github && !applyFlags.bufferLogs {
@@ -84,5 +86,6 @@ func applyFunc(cmd *cobra.Command, _ []string) error {
 		IgnoreChangeDetection: applyFlags.ignoreChangeDetection,
 		BufferLogs:            applyFlags.bufferLogs,
 		Github:                applyFlags.github,
+		Filters:               applyFlags.filters,
 	})
 }

internal/cmd/common.go

@@ -3,11 +3,12 @@ package cmd
 import (
 	"errors"
 	"fmt"
-	"github.com/mach-composer/mach-composer-cli/internal/cloud"
 	"os"
 	"path"
 	"path/filepath"
 
+	"github.com/mach-composer/mach-composer-cli/internal/cloud"
+
 	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
 
@@ -40,7 +41,7 @@ func registerCommonFlags(cmd *cobra.Command) {
 
 func preprocessCommonFlags(cmd *cobra.Command) {
 	if commonFlags.siteName != "" {
-		log.Warn().Msgf("Site option not implemented")
+		log.Warn().Msgf("Site option is deprecated. Please use `--filter your-site-name` instead.")
 	}
 
 	handleError(cmd.MarkFlagFilename("var-file", "yml", "yaml"))

internal/cmd/init.go

@@ -15,11 +15,12 @@ import (
 var initFlags struct {
 	github     bool
 	bufferLogs bool
+	filters    []string
 }
 
 var initCmd = &cobra.Command{
 	Use:   "init",
-	Short: "Initialize site directories Terraform files.",
+	Short: "Initialize site directories Terraform files. See [the documentation](/howto/cli/filtering-commands) for filtering options.",
 	PreRun: func(cmd *cobra.Command, args []string) {
 		preprocessCommonFlags(cmd)
 	},
@@ -36,6 +37,7 @@ func init() {
 	registerCommonFlags(initCmd)
 	initCmd.Flags().BoolVarP(&initFlags.github, "github", "g", false, "Whether logs should be decorated with github-specific formatting")
 	initCmd.Flags().BoolVarP(&initFlags.bufferLogs, "buffer", "b", false, "Whether logs should be buffered and printed at the end of the run")
+	initCmd.Flags().StringArrayVarP(&initFlags.filters, "filter", "", nil, "Run only nodes matching the filter expression")
 }
 
 func initFunc(cmd *cobra.Command, _ []string) error {
@@ -66,5 +68,6 @@ func initFunc(cmd *cobra.Command, _ []string) error {
 	return r.TerraformInit(ctx, dg, &runner.InitOptions{
 		BufferLogs: initFlags.bufferLogs,
 		Github:     initFlags.github,
+		Filters:    initFlags.filters,
 	})
 }

internal/cmd/plan.go

@@ -18,11 +18,12 @@ var planFlags struct {
 	ignoreChangeDetection bool
 	github                bool
 	bufferLogs            bool
+	filters               []string
 }
 
 var planCmd = &cobra.Command{
 	Use:   "plan",
-	Short: "Plan the configuration.",
+	Short: "Plan the configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.",
 	PreRun: func(cmd *cobra.Command, args []string) {
 		preprocessCommonFlags(cmd)
 	},
@@ -40,11 +41,12 @@ func init() {
 	planCmd.Flags().BoolVarP(&planFlags.ignoreChangeDetection, "ignore-change-detection", "", false, "Ignore change detection to run even if the components are considered up to date")
 	planCmd.Flags().BoolVarP(&planFlags.github, "github", "g", false, "Whether logs should be decorated with github-specific formatting")
 	planCmd.Flags().BoolVarP(&planFlags.bufferLogs, "buffer", "b", false, "Whether logs should be buffered and printed at the end of the run")
+	planCmd.Flags().StringArrayVarP(&planFlags.filters, "filter", "", nil, "Run only nodes matching the filter expression")
 }
 
 func planFunc(cmd *cobra.Command, _ []string) error {
 	if len(planFlags.components) > 0 {
-		log.Warn().Msgf("Components option not implemented")
+		log.Warn().Msgf("Component option is deprecated. Please use `--filter your-component-name instead.")
 	}
 
 	if planFlags.github && !planFlags.bufferLogs {
@@ -77,5 +79,6 @@ func planFunc(cmd *cobra.Command, _ []string) error {
 		IgnoreChangeDetection: planFlags.ignoreChangeDetection,
 		BufferLogs:            planFlags.bufferLogs,
 		Github:                planFlags.github,
+		Filters:               planFlags.filters,
 	})
 }

internal/cmd/show-plan.go

@@ -16,11 +16,12 @@ var showPlanFlags struct {
 	ignoreChangeDetection bool
 	github                bool
 	bufferLogs            bool
+	filters               []string
 }
 
 var showPlanCmd = &cobra.Command{
 	Use:   "show-plan",
-	Short: "Show the planned configuration.",
+	Short: "Show the planned configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.",
 	PreRun: func(cmd *cobra.Command, args []string) {
 		preprocessCommonFlags(cmd)
 	},
@@ -38,6 +39,7 @@ func init() {
 		"Ignore change detection to run even if the components are considered up to date")
 	showPlanCmd.Flags().BoolVarP(&showPlanFlags.github, "github", "g", false, "Whether logs should be decorated with github-specific formatting")
 	showPlanCmd.Flags().BoolVarP(&showPlanFlags.bufferLogs, "buffer", "b", false, "Whether logs should be buffered and printed at the end of the run")
+	showPlanCmd.Flags().StringArrayVarP(&showPlanFlags.filters, "filter", "", nil, "Run only nodes matching the filter expression.")
 }
 
 func showPlanFunc(cmd *cobra.Command, _ []string) error {
@@ -66,5 +68,6 @@ func showPlanFunc(cmd *cobra.Command, _ []string) error {
 		IgnoreChangeDetection: showPlanFlags.ignoreChangeDetection,
 		Github:                showPlanFlags.github,
 		BufferLogs:            showPlanFlags.bufferLogs,
+		Filters:               showPlanFlags.filters,
 	})
 }

internal/cmd/terraform.go

@@ -15,11 +15,12 @@ var terraformFlags struct {
 	ignoreChangeDetection bool
 	github                bool
 	bufferLogs            bool
+	filters               []string
 }
 
 var terraformCmd = &cobra.Command{
 	Use:   "terraform",
-	Short: "Execute terraform commands directly",
+	Short: "Execute terraform commands directly. See [the documentation](/howto/cli/filtering-commands) for filtering options.",
 	PreRun: func(cmd *cobra.Command, args []string) {
 		preprocessCommonFlags(cmd)
 	},
@@ -34,6 +35,7 @@ func init() {
 		"Ignore change detection to run even if the components are considered up to date. Per default the proxy will ignore change detection")
 	terraformCmd.Flags().BoolVarP(&terraformFlags.github, "github", "g", false, "Whether logs should be decorated with github-specific formatting")
 	terraformCmd.Flags().BoolVarP(&terraformFlags.bufferLogs, "buffer", "b", false, "Whether logs should be buffered and printed at the end of the run")
+	terraformCmd.Flags().StringArrayVarP(&terraformFlags.filters, "filter", "", nil, "Run only nodes matching the filter expression")
 }
 
 func terraformFunc(cmd *cobra.Command, args []string) error {
@@ -60,5 +62,6 @@ func terraformFunc(cmd *cobra.Command, args []string) error {
 		IgnoreChangeDetection: terraformFlags.ignoreChangeDetection,
 		Github:                terraformFlags.github,
 		BufferLogs:            terraformFlags.bufferLogs,
+		Filters:               terraformFlags.filters,
 	})
 }

internal/cmd/validate.go

@@ -1,15 +1,16 @@
 package cmd
 
 import (
+	"os"
+	"path"
+	"path/filepath"
+
 	"github.com/mach-composer/mach-composer-cli/internal/batcher"
 	"github.com/mach-composer/mach-composer-cli/internal/cli"
 	"github.com/mach-composer/mach-composer-cli/internal/graph"
 	"github.com/mach-composer/mach-composer-cli/internal/hash"
 	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
-	"os"
-	"path"
-	"path/filepath"
 
 	"github.com/mach-composer/mach-composer-cli/internal/generator"
 	"github.com/mach-composer/mach-composer-cli/internal/runner"
@@ -19,11 +20,12 @@ var validateFlags struct {
 	validationPath string
 	github         bool
 	bufferLogs     bool
+	filters        []string
 }
 
 var validateCmd = &cobra.Command{
 	Use:   "validate",
-	Short: "Validate the generated terraform configuration.",
+	Short: "Validate the generated terraform configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.",
 	Long: "This command validates the generated terraform configuration. It will check the provided configuration file " +
 		"for any errors, and will run `terraform validate` on the generated configuration. This will check for any " +
 		"syntax errors in the generated configuration without accessing the actual infrastructure.\n\n" +
@@ -46,6 +48,7 @@ func init() {
 		"Directory path to store files required for configuration validation.")
 	validateCmd.Flags().BoolVarP(&validateFlags.github, "github", "g", false, "Whether logs should be decorated with github-specific formatting")
 	validateCmd.Flags().BoolVarP(&validateFlags.bufferLogs, "buffer", "b", false, "Whether logs should be buffered and printed at the end of the run")
+	validateCmd.Flags().StringArrayVarP(&validateFlags.filters, "filter", "", nil, "Run only nodes matching the filter expression")
 
 	if path.IsAbs(validateFlags.validationPath) == false {
 		var err error
@@ -84,5 +87,6 @@ func validateFunc(cmd *cobra.Command, _ []string) error {
 	return r.TerraformValidate(ctx, dg, &runner.ValidateOptions{
 		BufferLogs: validateFlags.bufferLogs,
 		Github:     validateFlags.github,
+		Filters:    validateFlags.filters,
 	})
 }