Skip to content
Draft
Show file tree
Hide file tree
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
1 change: 1 addition & 0 deletions cmd/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -408,6 +408,7 @@ func run(cfg *Config) error {
selectionInfo,
cfg.ArgocdUIURL,
cfg.IgnoreResourceRules,
cfg.IgnoreArrayOrder,
)
if err != nil {
log.Error().Msg("❌ Failed to generate diff")
Expand Down
18 changes: 18 additions & 0 deletions cmd/options.go
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ import (
"k8s.io/klog/v2"

"github.com/dag-andersen/argocd-diff-preview/pkg/app_selector"
"github.com/dag-andersen/argocd-diff-preview/pkg/arrayorder"
"github.com/dag-andersen/argocd-diff-preview/pkg/cluster"
"github.com/dag-andersen/argocd-diff-preview/pkg/git"
"github.com/dag-andersen/argocd-diff-preview/pkg/k3d"
Expand Down Expand Up @@ -76,6 +77,7 @@ var (
DefaultWatchIfNoWatchPatternFound = true
DefaultIgnoreInvalidWatchPattern = false
DefaultHideDeletedAppDiff = false
DefaultIgnoreArrayOrder = ""
DefaultIgnoreResourceRules = ""
DefaultArgocdLoginOptions = ""
DefaultDisableClientThrottling = true
Expand Down Expand Up @@ -134,6 +136,7 @@ type RawOptions struct {
LogFormat string `mapstructure:"log-format"`
Title string `mapstructure:"title"`
HideDeletedAppDiff bool `mapstructure:"hide-deleted-app-diff"`
IgnoreArrayOrder string `mapstructure:"ignore-array-order"`
IgnoreResourceRules string `mapstructure:"ignore-resources"`
DisableClientThrottling bool `mapstructure:"disable-client-throttling"`
ArgocdUIURL string `mapstructure:"argocd-ui-url"`
Expand Down Expand Up @@ -199,6 +202,7 @@ type Config struct {
FilesChanged []string
RedirectRevisions []string
IgnoreResourceRules []resource_filter.IgnoreResourceRule
IgnoreArrayOrder []arrayorder.Rule
ClusterProvider cluster.Provider
}

Expand Down Expand Up @@ -282,6 +286,7 @@ func Parse() *Config {
viper.SetDefault("title", DefaultTitle)
viper.SetDefault("dry-run", DefaultDryRun)
viper.SetDefault("hide-deleted-app-diff", DefaultHideDeletedAppDiff)
viper.SetDefault("ignore-array-order", DefaultIgnoreArrayOrder)
viper.SetDefault("ignore-resources", DefaultIgnoreResourceRules)
viper.SetDefault("disable-client-throttling", DefaultDisableClientThrottling)
viper.SetDefault("concurrency", DefaultConcurrency)
Expand Down Expand Up @@ -348,6 +353,7 @@ func Parse() *Config {
rootCmd.Flags().String("redirect-target-revisions", "", "Comma-separated source targetRevision values to redirect to the target branch. Example: main,HEAD. By default, every targetRevision in matching repositories is redirected")
rootCmd.Flags().String("title", DefaultTitle, "Custom title for the markdown output")
rootCmd.Flags().Bool("hide-deleted-app-diff", DefaultHideDeletedAppDiff, "Hide diff content for fully deleted applications (only show deletion header)")
rootCmd.Flags().String("ignore-array-order", DefaultIgnoreArrayOrder, "Comma-separated JSONPaths of arrays whose element order is ignored in the diff. Example: '.spec.template.spec.containers[*].env'")
rootCmd.Flags().String("argocd-ui-url", DefaultArgocdUIURL, "Argo CD URL to generate application links in diff output (e.g., https://argocd.example.com)")
rootCmd.Flags().Bool("output-app-manifests", DefaultOutputAppManifests, "Write per-application manifest files to the output folder (output/base/ and output/target/)")
rootCmd.Flags().Bool("output-branch-manifests", DefaultOutputBranchManifests, "Write all application manifests per branch to a single file (output/base-branch.yaml and output/target-branch.yaml)")
Expand Down Expand Up @@ -491,6 +497,11 @@ func (o *RawOptions) ToConfig() (*Config, error) {
return nil, fmt.Errorf("invalid ignore-resources: %w", err)
}

cfg.IgnoreArrayOrder, err = arrayorder.FromString(o.IgnoreArrayOrder)
if err != nil {
return nil, fmt.Errorf("invalid ignore-array-order: %w", err)
}

// Parse redirect revisions
cfg.RedirectRevisions = o.parseRedirectRevisions()

Expand Down Expand Up @@ -837,6 +848,13 @@ func (o *Config) LogConfig() {
if o.HideDeletedAppDiff {
log.Info().Msgf("✨ - hide-deleted-app-diff: %t", o.HideDeletedAppDiff)
}
if len(o.IgnoreArrayOrder) > 0 {
paths := make([]string, len(o.IgnoreArrayOrder))
for i, rule := range o.IgnoreArrayOrder {
paths[i] = rule.String()
}
log.Info().Msgf("✨ - ignore-array-order: %s", strings.Join(paths, ", "))
}
if len(o.IgnoreResourceRules) > 0 {
ignoreResourceRuleStrings := make([]string, len(o.IgnoreResourceRules))
for i, ignoreResourceRule := range o.IgnoreResourceRules {
Expand Down
38 changes: 38 additions & 0 deletions cmd/options_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -61,3 +61,41 @@ func TestRawOptionsToConfig_IncludeHelmHooksRenderMethod(t *testing.T) {
})
}
}

func TestRawOptionsToConfig_IgnoreArrayOrder(t *testing.T) {
baseOptions := func(ignoreArrayOrder string) RawOptions {
return RawOptions{
BaseBranch: "main",
TargetBranch: "feature",
Repo: "example/repo",
RenderMethod: "cli",
DryRun: true,
IgnoreArrayOrder: ignoreArrayOrder,
}
}

t.Run("empty", func(t *testing.T) {
options := baseOptions("")
cfg, err := options.ToConfig()
require.NoError(t, err)
assert.Empty(t, cfg.IgnoreArrayOrder)
})

t.Run("parses list of paths", func(t *testing.T) {
options := baseOptions(".spec.template.spec.containers[*].env, ..volumeMounts\n{.spec.template.spec.volumes}")
cfg, err := options.ToConfig()
require.NoError(t, err)
var paths []string
for _, rule := range cfg.IgnoreArrayOrder {
paths = append(paths, rule.String())
}
assert.Equal(t, []string{".spec.template.spec.containers[*].env", "..volumeMounts", "{.spec.template.spec.volumes}"}, paths)
})

t.Run("rejects invalid path", func(t *testing.T) {
options := baseOptions(".spec.containers[?(@.name=='app')].env")
_, err := options.ToConfig()
require.Error(t, err)
assert.Contains(t, err.Error(), "invalid ignore-array-order")
})
}
41 changes: 41 additions & 0 deletions docs/filter-output.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,47 @@ This hides all lines containing the word `caBundle`.

---

## Ignore array order

Reordering list entries (e.g. environment variables after refactoring a Helm template) shows up as a diff, even though often nothing meaningful changed. Use `--ignore-array-order` with a list of JSONPath expressions (comma or newline separated). Every array matched by one of the paths is sorted into a canonical order before the diff is generated:

- If every element has a `name` field (e.g. `env`, `ports`, `volumes`, `volumeMounts`), the array is sorted by `name`.
- Otherwise, elements are sorted by their JSON representation.

```bash
# Environment variables of all containers in Deployments, StatefulSets, DaemonSets, Jobs, ...
argocd-diff-preview --ignore-array-order='.spec.template.spec.containers[*].env'

# Environment variables of Deployments only
argocd-diff-preview --ignore-array-order="\$[?(@.kind == 'Deployment')].spec.template.spec.containers[*].env"

# Environment variables of any container type, at any depth (also Pods, CronJobs, CRDs)
argocd-diff-preview --ignore-array-order='..containers[*].env,..initContainers[*].env'

# Volumes and volume mounts
argocd-diff-preview --ignore-array-order='.spec.template.spec.volumes,..containers[*].volumeMounts'
```

Supported JSONPath syntax (a subset of [kubectl JSONPath](https://kubernetes.io/docs/reference/kubectl/jsonpath/)):

| Syntax | Meaning |
| -------------- | -------------------------------------------------------- |
| `.field` | Child field |
| `..field` | Field at any depth (recursive descent) |
| `[*]` / `.*` | All array elements / all map values |
| `[n]` | Array element at index `n` |
| `['a.b/c']` | Field whose name contains special characters |
| `[?(@.kind == 'Deployment')]` | Root manifest string-field equality filter |

A leading `$` and kubectl-style braces (`{.spec...}`) are accepted. A root filter tests the current manifest, not an array of manifests. It supports `==` on a direct string field (such as `kind` or `apiVersion`), with single- or double-quoted string values. Nested filters, other operators, compound conditions, slices and unions are not supported. Paths that don't match anything in a resource are ignored.

Real changes (added, removed or modified elements) are still shown. The sorting only affects the diff - files written with `--output-app-manifests` or `--output-branch-manifests` keep the original order.

!!! warning
Array order is not always irrelevant. For example, Kubernetes only expands `$(VAR_NAME)` references to environment variables defined **earlier** in the list, and the order of `args`, `command` or `initContainers` matters. A reordering of a matched array will not show up in the diff.

---

## Ignore resources

Use `--ignore-resources` to exclude entire resources from the diff. The format is:
Expand Down
1 change: 1 addition & 0 deletions docs/options.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ argocd-diff-preview [FLAGS] [OPTIONS] (--repo <repo> | --repo-regex <regex>) --t
| `--diff-ignore <pattern>`, `-i` | `DIFF_IGNORE` | - | Ignore lines in diff. Example: `v[1,9]+.[1,9]+.[1,9]+` for ignoring version changes |
| `--file-regex <regex>`, `-r` | `FILE_REGEX` | - | Regex to filter files. Example: `/apps_.*\.yaml` |
| `--files-changed <files>` | `FILES_CHANGED` | - | List of files changed between branches (comma, space or newline separated) |
| `--ignore-array-order <paths>` | `IGNORE_ARRAY_ORDER` | - | JSONPaths of arrays whose element order is ignored in the diff (comma or newline separated). Example: `.spec.template.spec.containers[*].env` |
| `--ignore-resources <rules>` | `IGNORE_RESOURCES` | - | Ignore resources in diff. Format: `group:kind:name` (comma-separated, `*` wildcard) |
| `--k3d-options <options>` | `K3D_OPTIONS` | - | k3d options (only for k3d) |
| `--kind-options <options>` | `KIND_OPTIONS` | - | kind options (only for kind) |
Expand Down
7 changes: 7 additions & 0 deletions integration-test/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -190,6 +190,11 @@ Each `branch-N/target[-suffix]/` directory contains expected output files (`outp
- `branch-19/target`: Kustomize resource outside the application directory via `repo-server-api`. It requires global `kustomize.buildOptions: --load-restrictor LoadRestrictionsNone` from `argocd-cm`, proving the direct repo-server request forwards that setting.
- `branch-21/target`: Local Helm chart that gates a ServiceMonitor on the kind-level capability `monitoring.coreos.com/v1/ServiceMonitor`, via `repo-server-api` against a cluster with the ServiceMonitor CRD. The target enables it, so the diff must show the ServiceMonitor added, as a real Argo CD sync would render it.

### Branch 22: Ignore Array Order
Test data lives in the `quangkhainguyen/extended-argocd-diff-preview` fork (set via the `GitHubRepo` field). The target reorders `env`, `volumes` and `args` of a Deployment and changes one env var value.
- `target-1`: Without options - all reorderings show up in the diff
- `target-2`: `--ignore-array-order` on `env` and `volumes` - only the env value change and the `args` reorder remain

## Prerequisites

- Docker running
Expand Down Expand Up @@ -231,6 +236,7 @@ type TestCase struct {
MaxDiffLength string // --max-diff-length
HideDeletedAppDiff string // --hide-deleted-app-diff
IgnoreResources string // --ignore-resources
IgnoreArrayOrder string // --ignore-array-order
WatchIfNoWatchPatternFound string // --watch-if-no-watch-pattern-found
AutoDetectFilesChanged string // --auto-detect-files-changed (uses git diff)
IgnoreInvalidWatchPattern string // --ignore-invalid-watch-pattern
Expand All @@ -239,6 +245,7 @@ type TestCase struct {
// Cluster/Auth options
KindOptions string // --kind-options
CreateCluster string // "true" to force a new cluster for this test
GitHubRepo string // "owner/repo" to clone test branches from; defaults to dag-andersen/argocd-diff-preview
ArgocdLoginOptions string // --argocd-login-options
ArgocdAuthToken string // --argocd-auth-token (used instead of username/password login)
RenderMethod string // "cli", "server-api", "repo-server-api", or "" to use global -render-method flag
Expand Down
4 changes: 2 additions & 2 deletions integration-test/auth_token_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -106,10 +106,10 @@ func TestAuthToken(t *testing.T) {
_ = os.RemoveAll(targetBranchDir)
_ = os.RemoveAll(outputDir)

if err := cloneBranch("integration-test/branch-1/base", baseBranchDir); err != nil {
if err := cloneBranch(gitHubRepo(TestCase{}), "integration-test/branch-1/base", baseBranchDir); err != nil {
t.Fatalf("Failed to clone base branch: %v", err)
}
if err := cloneBranch("integration-test/branch-1/target", targetBranchDir); err != nil {
if err := cloneBranch(gitHubRepo(TestCase{}), "integration-test/branch-1/target", targetBranchDir); err != nil {
t.Fatalf("Failed to clone target branch: %v", err)
}

Expand Down
121 changes: 121 additions & 0 deletions integration-test/branch-22/target-1/output.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
<html>
<head>
<meta charset="utf-8">
<style>
body {
font-family: arial;
}
.container {
margin: auto;
width: 910px;
}
.diffs {
margin: 20px 0 20px 0;
}
.diff_container {
width: 910px;
overflow-x: scroll;
border-radius: 8px;
background:rgb(239, 239, 239);
scrollbar-width: none;
margin: 10px 0 10px 0;
}
table {
font-family: monospace;
border-spacing: 0px;
width: 100%;
}
tr.normal_line {
background:rgb(239, 239, 239);
}
tr.added_line {
background:rgb(169, 216, 184);
}
tr.removed_line {
background:rgb(247, 149, 173);
}
tr.comment_line {
background:rgb(197, 194, 194);
}
.resource_header {
font-family: monospace;
font-size: 14px;
color: rgb(80, 80, 80);
margin: 15px 0 5px 0;
padding: 0;
}
.resource_header:first-of-type {
margin-top: 10px;
}
pre {
margin: 0;
padding-left: 15px;
padding-right: 15px;
}
</style>
</head>
<body>
<div class="container">
<h1>Argo CD Diff Preview</h1>

<p>Summary:</p>
<pre>Modified (1):
± ignore-array-order (+5|-5)</pre>

<div class="diffs">
<details>
<summary>
ignore-array-order (examples/ignore-array-order/application.yaml)
</summary>

<h4 class="resource_header">Deployment: default/ignore-array-order</h4>
<div class="diff_container">
<table>

<tr class="normal_line"><td><pre> selector:</pre></td></tr>
<tr class="normal_line"><td><pre> matchLabels:</pre></td></tr>
<tr class="normal_line"><td><pre> app: ignore-array-order</pre></td></tr>
<tr class="normal_line"><td><pre> template:</pre></td></tr>
<tr class="normal_line"><td><pre> metadata:</pre></td></tr>
<tr class="normal_line"><td><pre> labels:</pre></td></tr>
<tr class="normal_line"><td><pre> app: ignore-array-order</pre></td></tr>
<tr class="normal_line"><td><pre> spec:</pre></td></tr>
<tr class="normal_line"><td><pre> containers:</pre></td></tr>
<tr class="normal_line"><td><pre> - args:</pre></td></tr>
<tr class="removed_line"><td><pre>- - --first</pre></td></tr>
<tr class="normal_line"><td><pre> - --second</pre></td></tr>
<tr class="added_line"><td><pre>+ - --first</pre></td></tr>
<tr class="normal_line"><td><pre> env:</pre></td></tr>
<tr class="added_line"><td><pre>+ - name: DB_PORT</pre></td></tr>
<tr class="added_line"><td><pre>+ value: &#34;5433&#34;</pre></td></tr>
<tr class="normal_line"><td><pre> - name: LOG_LEVEL</pre></td></tr>
<tr class="normal_line"><td><pre> value: info</pre></td></tr>
<tr class="normal_line"><td><pre> - name: DB_HOST</pre></td></tr>
<tr class="normal_line"><td><pre> value: postgres</pre></td></tr>
<tr class="removed_line"><td><pre>- - name: DB_PORT</pre></td></tr>
<tr class="removed_line"><td><pre>- value: &#34;5432&#34;</pre></td></tr>
<tr class="normal_line"><td><pre> image: nginx:1.27</pre></td></tr>
<tr class="normal_line"><td><pre> name: app</pre></td></tr>
<tr class="normal_line"><td><pre> volumeMounts:</pre></td></tr>
<tr class="normal_line"><td><pre> - mountPath: /etc/config</pre></td></tr>
<tr class="normal_line"><td><pre> name: config</pre></td></tr>
<tr class="normal_line"><td><pre> - mountPath: /var/cache</pre></td></tr>
<tr class="normal_line"><td><pre> name: cache</pre></td></tr>
<tr class="normal_line"><td><pre> volumes:</pre></td></tr>
<tr class="normal_line"><td><pre> - emptyDir: {}</pre></td></tr>
<tr class="removed_line"><td><pre>- name: config</pre></td></tr>
<tr class="removed_line"><td><pre>- - emptyDir: {}</pre></td></tr>
<tr class="normal_line"><td><pre> name: cache</pre></td></tr>
<tr class="added_line"><td><pre>+ - emptyDir: {}</pre></td></tr>
<tr class="added_line"><td><pre>+ name: config</pre></td></tr>
</table>
</div>

</details>
</div>

<pre>_Stats_:
[Applications: 2], [Full Run: Xs], [Rendering: Xs], [Cluster: Xs], [Argo CD: Xs]</pre>
</div>
</body>
</html>
55 changes: 55 additions & 0 deletions integration-test/branch-22/target-1/output.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
## Argo CD Diff Preview

Summary:
```yaml
Modified (1):
± ignore-array-order (+5|-5)
```

<details>
<summary>ignore-array-order (examples/ignore-array-order/application.yaml)</summary>
<br>

#### Deployment: default/ignore-array-order
```diff
selector:
matchLabels:
app: ignore-array-order
template:
metadata:
labels:
app: ignore-array-order
spec:
containers:
- args:
- - --first
- --second
+ - --first
env:
+ - name: DB_PORT
+ value: "5433"
- name: LOG_LEVEL
value: info
- name: DB_HOST
value: postgres
- - name: DB_PORT
- value: "5432"
image: nginx:1.27
name: app
volumeMounts:
- mountPath: /etc/config
name: config
- mountPath: /var/cache
name: cache
volumes:
- emptyDir: {}
- name: config
- - emptyDir: {}
name: cache
+ - emptyDir: {}
+ name: config
```
</details>

_Stats_:
[Applications: 2], [Full Run: Xs], [Rendering: Xs], [Cluster: Xs], [Argo CD: Xs]
Loading