Configuration

🚀Configuration

Advanced

Customize how Custy selects Git branches for cleanup.

Commandcusty cleanup branches

📦Category

Maintenance

🚀Quick Command

custy cleanup branches

---

configurationcleanupbranch

---

Overview

Branch Cleanup is primarily controlled through your project's config.toml.

Rather than requiring long command-line invocations, Custy allows teams to define consistent cleanup rules that apply across the entire project.

All cleanup decisions are derived from these configuration values.

---

💡Configuration Before Execution

Before removing any branch, Custy evaluates every configured cleanup rule.

Only branches satisfying all applicable filters become eligible for cleanup.

---

Cleanup Configuration

📋config.toml Cleanup Configuration Properties

Configuration fields available under the Branch Cleanup section of your project's config.toml. The following configuration fields control how Custy selects branches eligible for cleanup.

Property	Type	Description	Default	Required
include_prefixes	string[]	List of branch name prefixes eligible for cleanup.	-	Yes
merge_status	merged | unmerged | all	Restrict cleanup based on merge status.	merged	No
max_age	duration	Only consider branches older than the specified relative age.	-	No
before	date	Only consider branches whose latest commit occurred before a specific date.	-	No

---

Branch Prefixes

The most important configuration is:

include_prefixes = [
    "release/",
    "feature/",
]

Custy never attempts to clean every branch.

Instead, only branches whose names begin with one of the configured prefixes are considered.

For example:

• release/v2.0
• release/archive
• feature/login

would all become eligible for further evaluation.

Branches with different names are ignored.

---

⚠️Default Behavior

A newly initialized project uses:

include_prefixes = []

With an empty list, no branches are selected.

This safety mechanism prevents accidental branch deletion until a project explicitly defines which branch prefixes may be cleaned.

---

Merge Status

Merge status determines whether Custy considers:

Value	Description
merged	Only merged branches.
unmerged	Only unmerged branches.
all	Ignore merge status completely.

Most projects use the default:

merge_status = "merged"

to remove branches that have already been integrated into the main development history.

---

Relative Age Filter

The optional age filter excludes recently updated branches.

Example:

max_age = "30d"

Supported units include:

• minutes (m)
• hours (h)
• days (d)
• weeks (w)
• months (mo)
• years (y)

Only branches older than the configured duration are considered.

---

Absolute Date Filter

Instead of using a relative duration, you may specify an absolute cutoff date.

Example:

before = "2026-07-01"

Only branches whose most recent commit occurred before that date become eligible.

before and max_age are mutually exclusive.

---

Protected Branches

Regardless of the configured filters, Custy always protects important branches.

The default protected branches are:

• main
• master
• develop

Even if these branches match every configured filter, they are never removed.

---

💡Layered Filtering

Custy evaluates branch cleanup in multiple stages.

A branch must satisfy every applicable rule before it becomes eligible for deletion.

This layered filtering significantly reduces the risk of accidental cleanup.

---

Configuration Strategy

A recommended configuration for many projects looks like:

Terminal

bash

include_prefixes = [
    "release/",
]

merge_status = "merged"

max_age = "30d"

This configuration removes merged release branches that have not been updated for at least thirty days while leaving all other branches untouched.

---

What's Next?

Continue to the Workflow page to see how Custy evaluates these filters step by step before deleting any branches.