From 71716e7201819c69948ad096961bf0303ecc43c5 Mon Sep 17 00:00:00 2001 From: Max Kotliar Date: Tue, 12 May 2026 19:38:56 +0300 Subject: [PATCH] docs: use git worktrees instead of checkout for updating flags in docs Replace the pattern of `git checkout && make ` with `git worktree add /tmp/vm-* ` so that flag updates no longer switch the working tree of the current repository. Each variant (opensource, enterprise, cluster) gets its own worktree, removing the need to restore the original branch between steps. Also normalize dynamic default values in vmctl prometheus flags (-prom-tmp-dir-path) to `os.TempDir()` to reduce noisy diffs caused by machine-specific temp paths. --- docs/Makefile | 108 +++++++++++------- .../vmctl/vmctl_prometheus_flags.md | 2 +- 2 files changed, 65 insertions(+), 45 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 1a740fca1e..dae8c9f9c2 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -61,11 +61,11 @@ docs-update-vmsingle-flags: ifndef TAG $(error TAG must be provided to update flags in docs) endif - git checkout $(TAG) && $(MAKE) victoria-metrics && \ - ./bin/victoria-metrics -help > /tmp/victoria_metrics_common_flags_tmp.md + (cd /tmp/vm-opensource && $(MAKE) victoria-metrics) + (cd /tmp/vm-opensource && ./bin/victoria-metrics -help > /tmp/victoria_metrics_common_flags_tmp.md) - git checkout $(TAG)-enterprise && $(MAKE) victoria-metrics && \ - ./bin/victoria-metrics -help > /tmp/victoria_metrics_enterprise_flags_tmp.md + (cd /tmp/vm-enterprise && $(MAKE) victoria-metrics) + (cd /tmp/vm-enterprise && ./bin/victoria-metrics -help > /tmp/victoria_metrics_enterprise_flags_tmp.md) echo "$$FLAGS_HEADER" > docs/victoriametrics/victoria_metrics_common_flags.md && \ cat /tmp/victoria_metrics_common_flags_tmp.md >> docs/victoriametrics/victoria_metrics_common_flags.md && \ @@ -90,10 +90,11 @@ docs-update-vmauth-flags: ifndef TAG $(error TAG must be provided to update flags in docs) endif - git checkout $(TAG) && $(MAKE) vmauth && \ - ./bin/vmauth -help > /tmp/vmauth_common_flags_tmp.md - git checkout $(TAG)-enterprise && $(MAKE) vmauth && \ - ./bin/vmauth -help > /tmp/vmauth_enterprise_flags_tmp.md + (cd /tmp/vm-opensource && $(MAKE) vmauth) + (cd /tmp/vm-opensource && ./bin/vmauth -help > /tmp/vmauth_common_flags_tmp.md) + + (cd /tmp/vm-enterprise && $(MAKE) vmauth) + (cd /tmp/vm-enterprise && ./bin/vmauth -help > /tmp/vmauth_enterprise_flags_tmp.md) echo "$$FLAGS_HEADER" > docs/victoriametrics/vmauth_common_flags.md cat /tmp/vmauth_common_flags_tmp.md >> docs/victoriametrics/vmauth_common_flags.md @@ -115,11 +116,11 @@ docs-update-vmagent-flags: ifndef TAG $(error TAG must be provided to update flags in docs) endif - git checkout $(TAG) && $(MAKE) vmagent && \ - ./bin/vmagent -help > /tmp/vmagent_common_flags_tmp.md + (cd /tmp/vm-opensource && $(MAKE) vmagent) + (cd /tmp/vm-opensource && ./bin/vmagent -help > /tmp/vmagent_common_flags_tmp.md) - git checkout $(TAG)-enterprise && $(MAKE) vmagent && \ - ./bin/vmagent -help > /tmp/vmagent_enterprise_flags_tmp.md + (cd /tmp/vm-enterprise && $(MAKE) vmagent) + (cd /tmp/vm-enterprise && ./bin/vmagent -help > /tmp/vmagent_enterprise_flags_tmp.md) echo "$$FLAGS_HEADER" > docs/victoriametrics/vmagent_common_flags.md && \ cat /tmp/vmagent_common_flags_tmp.md >> docs/victoriametrics/vmagent_common_flags.md && \ @@ -143,11 +144,11 @@ docs-update-vmalert-flags: ifndef TAG $(error TAG must be provided to update flags in docs) endif - git checkout $(TAG) && $(MAKE) vmalert && \ - ./bin/vmalert -help > /tmp/vmalert_common_flags_tmp.md + (cd /tmp/vm-opensource && $(MAKE) vmalert) + (cd /tmp/vm-opensource && ./bin/vmalert -help > /tmp/vmalert_common_flags_tmp.md) - git checkout $(TAG)-enterprise && $(MAKE) vmalert && \ - ./bin/vmalert -help > /tmp/vmalert_enterprise_flags_tmp.md + (cd /tmp/vm-enterprise && $(MAKE) vmalert) + (cd /tmp/vm-enterprise && ./bin/vmalert -help > /tmp/vmalert_enterprise_flags_tmp.md) echo "$$FLAGS_HEADER" > docs/victoriametrics/vmalert_common_flags.md && \ cat /tmp/vmalert_common_flags_tmp.md >> docs/victoriametrics/vmalert_common_flags.md && \ @@ -170,11 +171,11 @@ docs-update-vmselect-flags: ifndef TAG $(error TAG must be provided to update flags in docs) endif - git checkout $(TAG)-cluster && $(MAKE) vmselect && \ - ./bin/vmselect -help > /tmp/vmselect_common_flags_tmp.md + (cd /tmp/vm-opensource-cluster && $(MAKE) vmselect) + (cd /tmp/vm-opensource-cluster && ./bin/vmselect -help > /tmp/vmselect_common_flags_tmp.md) - git checkout $(TAG)-enterprise-cluster && $(MAKE) vmselect && \ - ./bin/vmselect -help > /tmp/vmselect_enterprise_flags_tmp.md + (cd /tmp/vm-enterprise-cluster && $(MAKE) vmselect) + (cd /tmp/vm-enterprise-cluster && ./bin/vmselect -help > /tmp/vmselect_enterprise_flags_tmp.md) echo "$$FLAGS_HEADER" > docs/victoriametrics/vmselect_common_flags.md && \ cat /tmp/vmselect_common_flags_tmp.md >> docs/victoriametrics/vmselect_common_flags.md && \ @@ -199,11 +200,11 @@ docs-update-vminsert-flags: ifndef TAG $(error TAG must be provided to update flags in docs) endif - git checkout $(TAG)-cluster && $(MAKE) vminsert && \ - ./bin/vminsert -help > /tmp/vminsert_common_flags_tmp.md + (cd /tmp/vm-opensource-cluster && $(MAKE) vminsert) + (cd /tmp/vm-opensource-cluster && ./bin/vminsert -help > /tmp/vminsert_common_flags_tmp.md) - git checkout $(TAG)-enterprise-cluster && $(MAKE) vminsert && \ - ./bin/vminsert -help > /tmp/vminsert_enterprise_flags_tmp.md + (cd /tmp/vm-enterprise-cluster && $(MAKE) vminsert) + (cd /tmp/vm-enterprise-cluster && ./bin/vminsert -help > /tmp/vminsert_enterprise_flags_tmp.md) echo "$$FLAGS_HEADER" > docs/victoriametrics/vminsert_common_flags.md && \ cat /tmp/vminsert_common_flags_tmp.md >> docs/victoriametrics/vminsert_common_flags.md && \ @@ -235,11 +236,11 @@ docs-update-vmstorage-flags: ifndef TAG $(error TAG must be provided to update flags in docs) endif - git checkout $(TAG)-cluster && $(MAKE) vmstorage && \ - ./bin/vmstorage -help > /tmp/vmstorage_common_flags_tmp.md + (cd /tmp/vm-opensource-cluster && $(MAKE) vmstorage) + (cd /tmp/vm-opensource-cluster && ./bin/vmstorage -help > /tmp/vmstorage_common_flags_tmp.md) - git checkout $(TAG)-enterprise-cluster && $(MAKE) vmstorage && \ - ./bin/vmstorage -help > /tmp/vmstorage_enterprise_flags_tmp.md + (cd /tmp/vm-enterprise-cluster && $(MAKE) vmstorage) + (cd /tmp/vm-enterprise-cluster && ./bin/vmstorage -help > /tmp/vmstorage_enterprise_flags_tmp.md) echo "$$FLAGS_HEADER" > docs/victoriametrics/vmstorage_common_flags.md && \ cat /tmp/vmstorage_common_flags_tmp.md >> docs/victoriametrics/vmstorage_common_flags.md && \ @@ -263,13 +264,13 @@ docs-update-vmctl-flags: ifndef TAG $(error TAG must be provided to update flags in docs) endif - git checkout $(TAG) && $(MAKE) vmctl && \ - ./bin/vmctl -help > /tmp/vmctl_flags_tmp.md && \ - ./bin/vmctl opentsdb -help > /tmp/vmctl_opentsdb_flags_tmp.md && \ - ./bin/vmctl influx -help > /tmp/vmctl_influx_flags_tmp.md && \ - ./bin/vmctl remote-read -help > /tmp/vmctl_remote-read_flags_tmp.md && \ - ./bin/vmctl prometheus -help > /tmp/vmctl_prometheus_flags_tmp.md && \ - ./bin/vmctl vm-native -help > /tmp/vmctl_vm-native_flags_tmp.md + (cd /tmp/vm-opensource && $(MAKE) vmctl) + (cd /tmp/vm-opensource && ./bin/vmctl -help > /tmp/vmctl_flags_tmp.md) + (cd /tmp/vm-opensource && ./bin/vmctl opentsdb -help > /tmp/vmctl_opentsdb_flags_tmp.md) + (cd /tmp/vm-opensource && ./bin/vmctl influx -help > /tmp/vmctl_influx_flags_tmp.md) + (cd /tmp/vm-opensource && ./bin/vmctl remote-read -help > /tmp/vmctl_remote-read_flags_tmp.md) + (cd /tmp/vm-opensource && ./bin/vmctl prometheus -help > /tmp/vmctl_prometheus_flags_tmp.md) + (cd /tmp/vm-opensource && ./bin/vmctl vm-native -help > /tmp/vmctl_vm-native_flags_tmp.md) echo "$$FLAGS_HEADER" > docs/victoriametrics/vmctl/vmctl_flags.md && \ cat /tmp/vmctl_flags_tmp.md >> docs/victoriametrics/vmctl/vmctl_flags.md && \ @@ -306,6 +307,10 @@ endif # remove Version line and the actual version line from vmctl_flags.md to reduce diffs noise sed -i '/^VERSION:/,+1d' docs/victoriametrics/vmctl/vmctl_flags.md + # adjust flags with dynamic default values + # remove after https://github.com/VictoriaMetrics/VictoriaMetrics/issues/9680 implemented + sed -i '/prom-tmp-dir-path/ s|(default: "[^"]*")|(default: os.TempDir())|' docs/victoriametrics/vmctl/vmctl_prometheus_flags.md + # docs-update-flags updates flags in the documentation # using the actual binaries compiled from the provided $TAG. # The command also normalizes the output a bit. @@ -324,12 +329,27 @@ endif # Install using: brew install gnu-sed gawk # Add tools to PATH see how in `brew info gnu-sed` and `brew info gawk - orig_branch=$$(git rev-parse --abbrev-ref HEAD); \ - $(MAKE) docs-update-vmctl-flags && git checkout "$$orig_branch" && \ - $(MAKE) docs-update-vmsingle-flags && git checkout "$$orig_branch" && \ - $(MAKE) docs-update-vmalert-flags && git checkout "$$orig_branch" && \ - $(MAKE) docs-update-vmauth-flags && git checkout "$$orig_branch" && \ - $(MAKE) docs-update-vmagent-flags && git checkout "$$orig_branch" && \ - $(MAKE) docs-update-vmselect-flags && git checkout "$$orig_branch" && \ - $(MAKE) docs-update-vminsert-flags && git checkout "$$orig_branch" && \ - $(MAKE) docs-update-vmstorage-flags && git checkout "$$orig_branch" + rm -rf /tmp/vm-enterprise + git worktree remove /tmp/vm-enterprise || true + git worktree add /tmp/vm-enterprise $(TAG)-enterprise + + rm -rf /tmp/vm-enterprise-cluster + git worktree remove /tmp/vm-enterprise-cluster || true + git worktree add /tmp/vm-enterprise-cluster $(TAG)-enterprise-cluster + + rm -rf /tmp/vm-opensource + git worktree remove /tmp/vm-opensource || true + git worktree add /tmp/vm-opensource $(TAG) + + rm -rf /tmp/vm-opensource-cluster + git worktree remove /tmp/vm-opensource-cluster || true + git worktree add /tmp/vm-opensource-cluster $(TAG)-cluster + + $(MAKE) docs-update-vmctl-flags + $(MAKE) docs-update-vmsingle-flags + $(MAKE) docs-update-vmalert-flags + $(MAKE) docs-update-vmauth-flags + $(MAKE) docs-update-vmagent-flags + $(MAKE) docs-update-vmselect-flags + $(MAKE) docs-update-vminsert-flags + $(MAKE) docs-update-vmstorage-flags diff --git a/docs/victoriametrics/vmctl/vmctl_prometheus_flags.md b/docs/victoriametrics/vmctl/vmctl_prometheus_flags.md index 34d9c368cd..2040b964c5 100644 --- a/docs/victoriametrics/vmctl/vmctl_prometheus_flags.md +++ b/docs/victoriametrics/vmctl/vmctl_prometheus_flags.md @@ -29,7 +29,7 @@ OPTIONS: --prom-filter-time-end value The time filter in RFC3339 format to select timeseries with timestamp equal or lower than provided value. E.g. '2020-01-01T20:07:00Z' --prom-filter-label value Prometheus label name to filter timeseries by. E.g. '__name__' will filter timeseries by name. --prom-filter-label-value value Prometheus regular expression to filter label from "prom-filter-label" flag. (default: ".*") - --prom-tmp-dir-path value Path to directory to be used for temporary files. (default: "/var/folders/9b/rj_f77q52w57vnxx236qh51m0000gn/T/") + --prom-tmp-dir-path value Path to directory to be used for temporary files. (default: os.TempDir()) --vm-addr value VictoriaMetrics address to perform import requests. Should be the same as --httpListenAddr value for single-node version or vminsert component. When importing into the clustered version do not forget to set additionally --vm-account-id flag.