Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 53 additions & 3 deletions cli/structure/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -450,10 +450,16 @@ Example:
```
## .kbcignore

You can exclude specific configurations from the sync process by creating a `.kbcignore` file in the `.keboola` directory.
You can exclude specific configurations, configuration rows, or individual fields from the sync process by creating a `.kbcignore` file in the `.keboola` directory.

It is a plain text file where each line specifies a path to a configuration or configuration row in the format
`{component_id}/{configuration_id}/{row_id}`. The `row_id` is optional for [row-based configurations](https://help.keboola.com/components/#configuration-rows).
It is a plain text file where each line specifies either:

- A path to a **configuration or configuration row** to exclude entirely, in the format `{component_id}/{configuration_id}/{row_id}` (the `row_id` is optional for [row-based configurations](https://help.keboola.com/components/#configuration-rows)).
- A **field-level ignore** rule in the format `{component_id}/{configuration_id}:{field_name}`, which excludes a single field from synchronization while keeping the rest of the configuration managed by the CLI.

Comments (lines starting with `#`) and empty lines are ignored.

### Configuration and Row Ignore

Example `.kbcignore` file:

Expand All @@ -469,6 +475,50 @@ This excludes:

As a result, the `kbc sync pull` and `kbc sync push` commands will not synchronize these configurations.

### Field-Level Ignore

In addition to ignoring entire configurations or rows, you can ignore **individual fields** within a configuration.
This is useful when you want to manage most of a configuration via the CLI but let a specific field be controlled
exclusively in the Keboola UI (or vice versa).

The syntax is:

```
{component_id}/{configuration_id}:{field_name}
```

Where `field_name` is either:

- A **struct-level field** of the configuration — currently `isDisabled` is supported.
- A **dot-notation content key** referring to a path inside the configuration's `config.json` content, e.g., `schedule.cronTab`.

Example `.kbcignore` with field-level rules:

```
# Ignore the isDisabled flag — let the UI control whether this config is enabled
ex-generic-v2/798412456:isDisabled

# Ignore the cron schedule — let the UI control the schedule timing
keboola.scheduler/801234567:schedule.cronTab
```

Field-level ignore is **bidirectional**:

- **`kbc sync push`**: The remote value of the ignored field is kept. Any local change to that field is discarded before
the diff is computed, so the field is never pushed.
- **`kbc sync pull`**: The local value of the ignored field is kept. Any remote change to that field is discarded before
the diff is computed, so the field is never pulled.

In both cases the rest of the configuration is synchronized normally.

<div class="clearfix"></div><div class="alert alert-info" role="alert">
<p><strong>Note:</strong><br>
The field-level ignore format requires exactly two path segments before the colon
(<code>{component_id}/{configuration_id}</code>). The field name must not be empty or start/end with a dot.</p>
</div>

### Configuration-Level Ignore

**`kbc push` operation**

The `kbc push` command will skip the excluded configurations and will not push them back to the project, even if they exist or have been modified in the local folder structure.
Expand Down
Loading