inital commit
This commit is contained in:
@@ -0,0 +1,118 @@
|
||||
.TH BIGGEST 1 "December 2025" "User Commands"
|
||||
.SH NAME
|
||||
biggest \- list the largest files and directories within a limited depth
|
||||
|
||||
.SH SYNOPSIS
|
||||
.B biggest
|
||||
.RI [ \-n " COUNT" | \-\-number " COUNT" ]
|
||||
.RI [ \-p " GLOB_PATTERN" | \-\-pattern " GLOB_PATTERN" ]
|
||||
|
||||
.SH DESCRIPTION
|
||||
.B biggest
|
||||
scans the current directory tree to a maximum depth of three levels,
|
||||
including hidden files and directories, and prints the largest entries
|
||||
sorted by size.
|
||||
|
||||
Sizes are sorted using a block-based numeric size (via
|
||||
.BR du (1)
|
||||
with the
|
||||
.B -sk
|
||||
option), but displayed in human-readable form (e.g. 1K, 23M, 4.2G)
|
||||
using
|
||||
.BR du (1)
|
||||
with the
|
||||
.B -sh
|
||||
option. Permission-related errors and similar diagnostics are
|
||||
suppressed.
|
||||
|
||||
The command considers both files and directories and "rolls up" the
|
||||
size of directories as
|
||||
.B du
|
||||
does.
|
||||
|
||||
If no options are given, the default is to list the 20 largest entries
|
||||
that match the pattern "\fB*\fR".
|
||||
|
||||
.SH OPTIONS
|
||||
.TP
|
||||
.BR -n " " \fICOUNT\fR ", " --number =\fICOUNT\fR
|
||||
Set the number of entries to display (largest first). \fICOUNT\fR must
|
||||
be a positive integer. The default is 20.
|
||||
|
||||
.TP
|
||||
.BR -p " " \fIGLOB_PATTERN\fR ", " --pattern =\fIGLOB_PATTERN\fR
|
||||
Shell-style glob pattern used to filter file and directory names
|
||||
(e.g. "\fB*.log\fR", "\fBnode*\fR"). The pattern is applied by
|
||||
.BR find (1)
|
||||
via its
|
||||
.B -name
|
||||
predicate. The default pattern is "\fB*\fR", which matches all names.
|
||||
|
||||
.TP
|
||||
.BR -h ", " --help
|
||||
Display a short usage message and exit.
|
||||
|
||||
.SH BEHAVIOUR
|
||||
The search is limited to paths within three levels from the current
|
||||
directory:
|
||||
|
||||
.IP \[bu]
|
||||
\fB./*\fR
|
||||
.IP \[bu]
|
||||
\fB./*/*\fR
|
||||
.IP \[bu]
|
||||
\fB./*/*/*\fR
|
||||
|
||||
Hidden files and directories (names beginning with ".") are included as
|
||||
long as they match the specified pattern.
|
||||
|
||||
The command suppresses "permission denied" and similar error messages
|
||||
from underlying tools.
|
||||
|
||||
Output is colourised: the size field is printed in one colour and the
|
||||
path in another, subject to terminal support for ANSI escape codes.
|
||||
|
||||
.SH EXAMPLES
|
||||
.TP
|
||||
List the top 20 largest files and directories within three levels:
|
||||
.PP
|
||||
.nf
|
||||
.RS
|
||||
biggest
|
||||
.RE
|
||||
.fi
|
||||
|
||||
.TP
|
||||
List the top 50 largest entries:
|
||||
.PP
|
||||
.nf
|
||||
.RS
|
||||
biggest -n 50
|
||||
.RE
|
||||
.fi
|
||||
|
||||
.TP
|
||||
List the top 20 largest log files:
|
||||
.PP
|
||||
.nf
|
||||
.RS
|
||||
biggest -p "*.log"
|
||||
.RE
|
||||
.fi
|
||||
|
||||
.TP
|
||||
Use both options together:
|
||||
.PP
|
||||
.nf
|
||||
.RS
|
||||
biggest -n 100 -p "node*"
|
||||
.RE
|
||||
.fi
|
||||
|
||||
.SH SEE ALSO
|
||||
.BR du (1),
|
||||
.BR find (1),
|
||||
.BR zsh (1)
|
||||
|
||||
.SH AUTHOR
|
||||
Written by the user and maintained locally.
|
||||
@@ -0,0 +1,79 @@
|
||||
.TH COMPINIT_DOCTOR 1 "2025-11-11" "compinit_doctor" "User Commands"
|
||||
.SH NAME
|
||||
compinit_doctor \- inspect, audit, diff, and rebuild zsh completion state
|
||||
.SH SYNOPSIS
|
||||
.B compinit_doctor
|
||||
.RI [ --status ]
|
||||
.RI [ --audit ]
|
||||
.RI [ --rebuild ]
|
||||
.RI [ --snap\ FILE ]
|
||||
.RI [ --diff\ FILE ]
|
||||
.RI [ --dump\ PATH ]
|
||||
.RI [ --json ]
|
||||
.RI [ --help ]
|
||||
.SH DESCRIPTION
|
||||
.B compinit_doctor
|
||||
is an autoloaded zsh function that diagnoses the shell completion system.
|
||||
It reports the zcompdump location and age, compiled dump presence, basic
|
||||
health of the completion setup, and can optionally rebuild the dump, snapshot
|
||||
the current
|
||||
.I $fpath
|
||||
and perform diffs against a previous snapshot.
|
||||
.SH OPTIONS
|
||||
.TP
|
||||
.BR --status , " -s"
|
||||
Show current compinit and zcompdump status (default action).
|
||||
.TP
|
||||
.BR --audit , " -a"
|
||||
Run
|
||||
.B compaudit
|
||||
and list insecure directories or files.
|
||||
.TP
|
||||
.BR --rebuild , " -r"
|
||||
Force
|
||||
.B compinit -i
|
||||
using the configured dump path and background
|
||||
.BR zcompile .
|
||||
.TP
|
||||
.BR --snap " " \fIFILE\fR , " -S " \fIFILE\fR
|
||||
Snapshot the current (sorted)
|
||||
.I $fpath
|
||||
to
|
||||
.IR FILE .
|
||||
.TP
|
||||
.BR --diff " " \fIFILE\fR , " -d " \fIFILE\fR
|
||||
Compare the current (sorted)
|
||||
.I $fpath
|
||||
to a snapshot
|
||||
.IR FILE ,
|
||||
reporting added and removed paths.
|
||||
.TP
|
||||
.BR --dump " " \fIPATH\fR , " -D " \fIPATH\fR
|
||||
Override the zcompdump path (default:
|
||||
.IR $XDG_CACHE_HOME/zcompdump ).
|
||||
.TP
|
||||
.BR --json , " -j"
|
||||
Emit the status as a single JSON object (machine readable).
|
||||
.TP
|
||||
.BR --help , " -h"
|
||||
Show usage.
|
||||
.SH ENVIRONMENT
|
||||
.TP
|
||||
.B ZCOMP_DUMP_PATH
|
||||
Overrides the zcompdump file path.
|
||||
.SH FILES
|
||||
.TP
|
||||
.I ~/.cache/zcompdump
|
||||
Default zcompdump file read by
|
||||
.BR compinit .
|
||||
.TP
|
||||
.I ~/.cache/zcompdump.zwc
|
||||
Optional compiled dump file created by
|
||||
.BR zcompile .
|
||||
.SH EXIT STATUS
|
||||
Returns 0 on success; non\-zero on argument or runtime errors.
|
||||
.SH SEE ALSO
|
||||
.BR zsh (1),
|
||||
.BR compinit (1),
|
||||
.BR compaudit (1),
|
||||
.BR zcompile (1)
|
||||
@@ -0,0 +1,127 @@
|
||||
.TH CONFE 1 "2025" "User Commands"
|
||||
.SH NAME
|
||||
confe \- edit configuration files with optional backup and git staging
|
||||
.SH SYNOPSIS
|
||||
.B confe
|
||||
[\fB--backup\fR | \fB-b\fR]
|
||||
[\fB--staged\fR | \fB-s\fR]
|
||||
\fITOPIC\fR
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
.B confe
|
||||
command provides a unified interface for editing a set of known
|
||||
configuration files. Each topic corresponds to a specific file path,
|
||||
and the command can optionally perform a backup of the file before
|
||||
editing, or stage the file into a git repository afterwards.
|
||||
|
||||
The editing action itself is performed by an external executable,
|
||||
determined in the following order:
|
||||
.IP \(bu 3
|
||||
The value of the environment variable \fBCONFE_EDIT_CMD\fR
|
||||
.IP \(bu 3
|
||||
The user's \fBEDITOR\fR variable
|
||||
.IP \(bu 3
|
||||
A fallback to \fBecho\fR
|
||||
|
||||
File backups are performed using the command referenced in
|
||||
\fBCONFE_BACKUP_CMD\fR, falling back to \fBecho\fR if unset.
|
||||
|
||||
The function ensures that when staging is requested, the file is only
|
||||
added if it resides inside an actual git repository.
|
||||
|
||||
.SH TOPICS
|
||||
The following topics are supported:
|
||||
|
||||
.TP
|
||||
.B alias
|
||||
The user's shell alias configuration file.
|
||||
|
||||
.TP
|
||||
.B keybindings
|
||||
Shell keybinding configuration file.
|
||||
|
||||
.TP
|
||||
.B options
|
||||
General shell options file.
|
||||
|
||||
.TP
|
||||
.B path
|
||||
Shell path configuration file.
|
||||
|
||||
.TP
|
||||
.B packages
|
||||
A custom list of package declarations.
|
||||
|
||||
.TP
|
||||
.B ssh
|
||||
SSH client configuration file (typically \fI~/.ssh/config\fR).
|
||||
|
||||
.TP
|
||||
.B brewfile
|
||||
The user's Brewfile.
|
||||
|
||||
.SH OPTIONS
|
||||
.TP
|
||||
.B --backup, -b
|
||||
Before editing, the file is passed to a backup helper. This helper is a
|
||||
dummy command by default and must be implemented by the user.
|
||||
|
||||
.TP
|
||||
.B --staged, -s
|
||||
After editing, the file is staged into the git repository it belongs to.
|
||||
The command checks that the file resides within a valid git work tree.
|
||||
|
||||
.SH ENVIRONMENT
|
||||
.TP
|
||||
.B CONFE_EDIT_CMD
|
||||
Defines the editor executable. Overrides \fBEDITOR\fR.
|
||||
|
||||
.TP
|
||||
.B CONFE_BACKUP_CMD
|
||||
Defines the backup executable. If unset, backups use \fBecho\fR.
|
||||
|
||||
.SH EXIT STATUS
|
||||
The command exits with:
|
||||
.TP
|
||||
0
|
||||
Success.
|
||||
.TP
|
||||
>0
|
||||
Failure in backup, edit, staging, or invalid topic.
|
||||
|
||||
.SH EXAMPLES
|
||||
Edit alias file normally:
|
||||
.PP
|
||||
.nf
|
||||
confe alias
|
||||
.fi
|
||||
|
||||
Backup first, then edit keybindings:
|
||||
.PP
|
||||
.nf
|
||||
confe --backup keybindings
|
||||
.fi
|
||||
|
||||
Edit and automatically stage path file:
|
||||
.PP
|
||||
.nf
|
||||
confe -s path
|
||||
.fi
|
||||
|
||||
Backup + edit + stage:
|
||||
.PP
|
||||
.nf
|
||||
confe -b -s options
|
||||
.fi
|
||||
|
||||
Override editor:
|
||||
.PP
|
||||
.nf
|
||||
CONFE_EDIT_CMD=nvim confe packages
|
||||
.fi
|
||||
|
||||
.SH AUTHOR
|
||||
Generated automatically upon request.
|
||||
|
||||
.SH SEE ALSO
|
||||
zsh(1), git(1), editor(1)
|
||||
@@ -0,0 +1,342 @@
|
||||
.TH DCSCTL 1 "2026" "User Commands"
|
||||
.SH NAME
|
||||
dcsctl \- control-plane CLI for Docker Compose and Docker Swarm stacks
|
||||
.SH SYNOPSIS
|
||||
.B dcsctl
|
||||
\fIcommand\fR [\fIarguments\fR] [\fIflags\fR]
|
||||
.SH DESCRIPTION
|
||||
.B dcsctl
|
||||
provides a structured control-plane for managing Docker Compose and Docker
|
||||
Swarm projects. It enforces a consistent file and directory layout,
|
||||
manages environment variable layering across stack and per-service
|
||||
scopes, handles bind-mount permission enforcement, and supports
|
||||
deploying to Docker Swarm with automatic compose fragment merging
|
||||
and variable resolution.
|
||||
.PP
|
||||
Projects operate in one of two modes:
|
||||
.TP
|
||||
.B compose mode
|
||||
(legacy) A flat layout with a single
|
||||
.I docker-compose.yml
|
||||
at the project root and shared
|
||||
.IR service.env / service.secrets.env
|
||||
files. Managed with
|
||||
.BR "dcsctl run" ", " "dcsctl up" ", " "dcsctl down" .
|
||||
.TP
|
||||
.B swarm mode
|
||||
(default for new projects) Each service lives in its own subdirectory
|
||||
under
|
||||
.IR services/ ,
|
||||
with per-service compose fragments and env files. At deploy time,
|
||||
fragments are merged, environment variables resolved, and the result
|
||||
written as
|
||||
.I docker-compose.resolved.yml
|
||||
for use with
|
||||
.BR "docker stack deploy" .
|
||||
Managed with
|
||||
.BR "dcsctl deploy" " and " "dcsctl down" .
|
||||
.PP
|
||||
Mode is detected automatically: if a project has a
|
||||
.I services/
|
||||
directory, it is treated as swarm mode; otherwise compose mode.
|
||||
.SH PROJECT LAYOUT
|
||||
.SS Swarm mode (default)
|
||||
.nf
|
||||
~/.dcs/<context>/compose/<project>/
|
||||
\(ba\(em .env stack-level orchestration vars
|
||||
\(ba\(em services/
|
||||
\(ba \(ba\(em traefik/
|
||||
\(ba \(ba \(ba\(em compose.yml service compose fragment
|
||||
\(ba \(ba \(ba\(em service.env service runtime config
|
||||
\(ba \(ba \(ba\(em service.secrets.env service secrets
|
||||
\(ba \(ba\(em app/
|
||||
\(ba \(ba\(em compose.yml
|
||||
\(ba \(ba\(em service.env
|
||||
\(ba \(ba\(em service.secrets.env
|
||||
\(ba\(em docker-compose.resolved.yml generated at deploy time
|
||||
\(ba\(em secrets/
|
||||
\(ba\(em .gitignore
|
||||
.fi
|
||||
.SS Compose mode (legacy)
|
||||
.nf
|
||||
~/.dcs/<context>/compose/<project>/
|
||||
\(ba\(em docker-compose.yml
|
||||
\(ba\(em .env
|
||||
\(ba\(em service.env
|
||||
\(ba\(em service.secrets.env
|
||||
\(ba\(em secrets/
|
||||
\(ba\(em .gitignore
|
||||
.fi
|
||||
.SH COMMANDS
|
||||
.SS Project creation
|
||||
.TP
|
||||
.BI "dcsctl new " "project " "[flags]"
|
||||
Create a new project. By default creates a swarm-mode layout with an
|
||||
initial service named
|
||||
.BR app .
|
||||
.RS
|
||||
.TP
|
||||
.B \-\-compose
|
||||
Create a legacy flat compose layout instead.
|
||||
.TP
|
||||
.BI \-\-service " name"
|
||||
Name the initial service (default:
|
||||
.BR app ).
|
||||
Only applies in swarm mode.
|
||||
.TP
|
||||
.BR \-v ", " \-\-verify
|
||||
Run verification after creating the project.
|
||||
.TP
|
||||
.B \-\-verbose
|
||||
Verbose verification output (used with
|
||||
.BR \-\-verify ).
|
||||
.RE
|
||||
.SS Deployment
|
||||
.TP
|
||||
.BI "dcsctl deploy " "project " "[flags]"
|
||||
Merge all service compose fragments, resolve environment variables,
|
||||
write
|
||||
.IR docker-compose.resolved.yml ,
|
||||
and run
|
||||
.BR "docker stack deploy" .
|
||||
Only available for swarm-mode projects.
|
||||
.RS
|
||||
.TP
|
||||
.BR \-v ", " \-\-verify
|
||||
Run verification before deploying.
|
||||
.TP
|
||||
.B \-\-verbose
|
||||
Verbose verification output.
|
||||
.RE
|
||||
.TP
|
||||
.BI "dcsctl up " "project " "[flags]"
|
||||
Alias for
|
||||
.BR "dcsctl run " "\fIproject\fR up -d" .
|
||||
Only available for compose-mode projects. Swarm-mode projects should
|
||||
use
|
||||
.BR "dcsctl deploy" .
|
||||
.RS
|
||||
.TP
|
||||
.BR \-v ", " \-\-verify
|
||||
Run verification before starting.
|
||||
.RE
|
||||
.TP
|
||||
.BI "dcsctl stop " project
|
||||
Scale all services in a deployed swarm stack to 0 replicas, leaving the
|
||||
stack definition in place. Use
|
||||
.BR "dcsctl deploy"
|
||||
to resume. Only available for swarm-mode projects.
|
||||
.TP
|
||||
.BI "dcsctl down " project
|
||||
Bring down a project. For compose-mode projects, runs
|
||||
.BR "docker compose down" .
|
||||
For swarm-mode projects, runs
|
||||
.BR "docker stack rm" .
|
||||
.TP
|
||||
.BI "dcsctl run " "project " "[docker compose args...]"
|
||||
Run docker compose with the project's context and environment files.
|
||||
Compose-mode only. All arguments after the project name are passed
|
||||
directly to
|
||||
.BR "docker compose" .
|
||||
.TP
|
||||
.BI "dcsctl reload " project
|
||||
Down, rebuild, then up a project (compose mode).
|
||||
.SS Service management
|
||||
.TP
|
||||
.BI "dcsctl service add " "project service-name"
|
||||
Add a new service to a swarm-mode project. Creates the service
|
||||
subdirectory with compose fragment template, service.env, and
|
||||
service.secrets.env.
|
||||
.TP
|
||||
.BI "dcsctl service ls " project
|
||||
List services in a swarm-mode project.
|
||||
.SS Verification
|
||||
.TP
|
||||
.BI "dcsctl verify " "project " "[flags]"
|
||||
Verify and enforce host permissions for bind-mounted appdata
|
||||
directories. Applies compose fixups (docker.sock group_add,
|
||||
single-service normalization). For swarm-mode projects, checks
|
||||
all service fragments.
|
||||
.RS
|
||||
.TP
|
||||
.B \-\-verbose
|
||||
Show current vs expected ownership/mode while verifying.
|
||||
.RE
|
||||
.SS Editing
|
||||
.TP
|
||||
.BI "dcsctl edit " "project " "[flags]"
|
||||
Open a project file in
|
||||
.BR $EDITOR .
|
||||
Defaults to the compose file.
|
||||
.RS
|
||||
.TP
|
||||
.BR \-e ", " \-\-env
|
||||
Edit the stack-level .env file.
|
||||
.TP
|
||||
.BR \-r ", " \-\-runtime
|
||||
Edit service.env (or per-service service.env if
|
||||
.B \-\-service
|
||||
is specified).
|
||||
.TP
|
||||
.BR \-s ", " \-\-secret
|
||||
Edit service.secrets.env (or per-service service.secrets.env if
|
||||
.B \-\-service
|
||||
is specified).
|
||||
.TP
|
||||
.BI \-\-service " name"
|
||||
Target a specific service's files (swarm mode). When combined with
|
||||
.B \-\-env
|
||||
, always edits the stack-level .env.
|
||||
.RE
|
||||
.SS Secrets
|
||||
.TP
|
||||
.BI "dcsctl secret add " "project name"
|
||||
Create or edit
|
||||
.IR secrets/<name>.txt
|
||||
in
|
||||
.BR $EDITOR .
|
||||
.SS Import
|
||||
.TP
|
||||
.BI "dcsctl import " "project compose-path " "[flags]"
|
||||
Import an existing docker-compose.yml into a DCS project.
|
||||
Routes environment variables to the appropriate DCS layers.
|
||||
.RS
|
||||
.TP
|
||||
.BI \-\-env\-file " path"
|
||||
Additional env file to ingest alongside env_file references
|
||||
found in the compose.
|
||||
.TP
|
||||
.B \-\-strict
|
||||
Fail if the compose violates the template contract after import.
|
||||
.TP
|
||||
.B \-\-swarm
|
||||
Import as a swarm project, splitting each service into its own
|
||||
subdirectory under
|
||||
.IR services/ .
|
||||
.RE
|
||||
.SS Project management
|
||||
.TP
|
||||
.BI "dcsctl rename " "project new-name"
|
||||
Rename a project directory and update all env metadata references.
|
||||
.TP
|
||||
.BI "dcsctl dir " "project " "[service]"
|
||||
Print the resolved compose project directory path. If
|
||||
.I service
|
||||
is specified and the project is in swarm mode, prints the path to
|
||||
.IR services/<service>
|
||||
instead.
|
||||
.TP
|
||||
.B dcsctl ls
|
||||
List all running compose stacks (alias for
|
||||
.BR "docker compose ls" ).
|
||||
.SS Context management
|
||||
.TP
|
||||
.BI "dcsctl context init " "[context]"
|
||||
Initialize
|
||||
.I ~/.dcs/<context>
|
||||
with
|
||||
.I env.system
|
||||
and
|
||||
.IR compose/ .
|
||||
If no context is specified, uses the current Docker context.
|
||||
.SH ENVIRONMENT
|
||||
.TP
|
||||
.B DCS_ROOT
|
||||
Base directory for all DCS contexts. Defaults to
|
||||
.IR ~/.dcs .
|
||||
.TP
|
||||
.B DCS_CONTEXT_ROOT
|
||||
Override the context root directory. Defaults to
|
||||
.IR $DCS_ROOT/<context> .
|
||||
.TP
|
||||
.B EDITOR
|
||||
Editor used by
|
||||
.B edit
|
||||
and
|
||||
.B secret add
|
||||
commands. Falls back to
|
||||
.BR vi .
|
||||
.SH FILES
|
||||
.TP
|
||||
.I ~/.dcs/<context>/env.system
|
||||
Context-level environment overrides (HOST_DATA_ROOT, APPDATA_UID, etc.).
|
||||
.TP
|
||||
.I ~/.dcs/<context>/compose/<project>/.env
|
||||
Stack-level orchestration variables (DCS_PROJ_NAME, DCS_STACK_NAME,
|
||||
DCS_NET_NAME, HOST_DATA_ROOT, BASE_DIR).
|
||||
.TP
|
||||
.I services/*/compose.yml
|
||||
Per-service compose fragments (swarm mode).
|
||||
.TP
|
||||
.I services/*/service.env
|
||||
Per-service runtime configuration (swarm mode).
|
||||
.TP
|
||||
.I services/*/service.secrets.env
|
||||
Per-service secrets (swarm mode). Not committed to version control.
|
||||
.TP
|
||||
.I docker-compose.resolved.yml
|
||||
Fully resolved compose file generated by
|
||||
.BR deploy .
|
||||
All variables substituted, env_file directives inlined. Not committed
|
||||
to version control.
|
||||
.SH EXIT STATUS
|
||||
.TP
|
||||
0
|
||||
Success.
|
||||
.TP
|
||||
>0
|
||||
Failure. Error message printed to stderr.
|
||||
.SH EXAMPLES
|
||||
Create a new swarm-mode project:
|
||||
.PP
|
||||
.nf
|
||||
dcsctl new mystack
|
||||
.fi
|
||||
.PP
|
||||
Create with a custom initial service name:
|
||||
.PP
|
||||
.nf
|
||||
dcsctl new mystack --service traefik
|
||||
.fi
|
||||
.PP
|
||||
Create a legacy compose-mode project:
|
||||
.PP
|
||||
.nf
|
||||
dcsctl new mystack --compose
|
||||
.fi
|
||||
.PP
|
||||
Add a service to a swarm project:
|
||||
.PP
|
||||
.nf
|
||||
dcsctl service add mystack redis
|
||||
.fi
|
||||
.PP
|
||||
Deploy a swarm project:
|
||||
.PP
|
||||
.nf
|
||||
dcsctl deploy mystack
|
||||
dcsctl deploy mystack --verify
|
||||
.fi
|
||||
.PP
|
||||
Edit a specific service's env:
|
||||
.PP
|
||||
.nf
|
||||
dcsctl edit mystack --service traefik --runtime
|
||||
.fi
|
||||
.PP
|
||||
Import an existing compose as a swarm project:
|
||||
.PP
|
||||
.nf
|
||||
dcsctl import mystack /path/to/docker-compose.yml --swarm
|
||||
.fi
|
||||
.PP
|
||||
Run docker compose commands (compose mode):
|
||||
.PP
|
||||
.nf
|
||||
dcsctl run myapp logs -f
|
||||
dcsctl up myapp --verify
|
||||
dcsctl down myapp
|
||||
.fi
|
||||
.SH SEE ALSO
|
||||
.BR docker (1),
|
||||
.BR docker-compose (1)
|
||||
@@ -0,0 +1,80 @@
|
||||
.\" ===========================================================================
|
||||
.\" dotfiles_doctor.1 — Manual page for the dotfiles_doctor utility
|
||||
.\" ===========================================================================
|
||||
.TH DOTFILES_DOCTOR 1 "2025-11-06" "dotfiles_doctor" "User Commands"
|
||||
.SH NAME
|
||||
dotfiles_doctor \- analyze zsh startup health, timings, and timeline from NDJSON logs
|
||||
.SH SYNOPSIS
|
||||
.B dotfiles_doctor
|
||||
.RI [ --timeline ]
|
||||
.RI [ --logfile= PATH ]
|
||||
.SH DESCRIPTION
|
||||
.B dotfiles_doctor
|
||||
reads an NDJSON log (newline\-delimited JSON objects) produced by your
|
||||
.ZN call_file
|
||||
logger during shell startup and prints a health report:
|
||||
per\-file durations, exit codes, aggregate timings, and optionally a
|
||||
microsecond\-precision load timeline.
|
||||
|
||||
The log entries are emitted one JSON object per line (not a single JSON array).
|
||||
The tool always "slurps" the file internally.
|
||||
.SH OPTIONS
|
||||
.TP
|
||||
.BR --timeline
|
||||
Show a start\->end timeline for each loaded file with microsecond timestamps.
|
||||
.TP
|
||||
.BR --logfile = PATH
|
||||
Path to the NDJSON log file to analyze. Defaults to
|
||||
.IR ~/zshrc\-log.json .
|
||||
.SH ENVIRONMENT
|
||||
.TP
|
||||
.B SLOW_THRESHOLD
|
||||
Duration (ms) above which a module is flagged "slow". Default: 200.
|
||||
.TP
|
||||
.B WARN_THRESHOLD
|
||||
Duration (ms) above which a module is flagged "warning/very slow". Default: 500.
|
||||
.SH REQUIREMENTS
|
||||
The script relies on
|
||||
.BR jq (1),
|
||||
.BR awk (1),
|
||||
.BR column (1),
|
||||
and standard shell utilities.
|
||||
.SH FILES
|
||||
.TP
|
||||
.I ~/zshrc\-log.json
|
||||
Default NDJSON log consumed by
|
||||
.B dotfiles_doctor .
|
||||
Each line is a JSON object with keys:
|
||||
.BR file ,
|
||||
.BR label ,
|
||||
.BR start ,
|
||||
.BR end ,
|
||||
.BR duration_ms ,
|
||||
.BR exit_code .
|
||||
.SH EXIT STATUS
|
||||
Returns 0 on success; non\-zero on invocation errors (e.g. missing jq or log file).
|
||||
.SH EXAMPLES
|
||||
Analyze with defaults:
|
||||
.P
|
||||
.EX
|
||||
dotfiles_doctor
|
||||
.EE
|
||||
.P
|
||||
Show microsecond timeline:
|
||||
.P
|
||||
.EX
|
||||
dotfiles_doctor --timeline
|
||||
.EE
|
||||
.P
|
||||
Use a custom log and tighter thresholds:
|
||||
.P
|
||||
.EX
|
||||
SLOW_THRESHOLD=100 WARN_THRESHOLD=300 dotfiles_doctor \\
|
||||
--logfile="$HOME/tmp/startup.ndjson" --timeline
|
||||
.EE
|
||||
.SH SEE ALSO
|
||||
.BR jq (1),
|
||||
.BR zsh (1),
|
||||
.BR compinit (1)
|
||||
.SH AUTHOR
|
||||
Written for your dotfiles; completion and manpage generated by ChatGPT.
|
||||
@@ -0,0 +1,139 @@
|
||||
.TH FIND_DUPES 1 "December 2025" "find_dupes 1.0" "User Commands"
|
||||
.SH NAME
|
||||
find_dupes \- find duplicated lines across shell-related files
|
||||
.SH SYNOPSIS
|
||||
.B find_dupes
|
||||
.RI [ --maxdepth\ N | -d\ N ]
|
||||
.RI [ --regex\ PATTERN | -r\ PATTERN ]
|
||||
.RI [ --ignore-case | -i ]
|
||||
.SH DESCRIPTION
|
||||
.B find_dupes
|
||||
recursively searches for duplicated lines across files below the current
|
||||
directory. Only files with no extension, or with the extensions
|
||||
.BR .zsh ,
|
||||
.BR .sh ,
|
||||
.BR .zlogin
|
||||
or
|
||||
.BR .symlink
|
||||
are considered.
|
||||
|
||||
Lines that are comments (first non\-whitespace character is
|
||||
.BR # ),
|
||||
blank or whitespace\-only lines, and lines shorter than five characters
|
||||
are ignored.
|
||||
|
||||
The search is limited to a maximum directory recursion depth, and
|
||||
optionally to lines matching a supplied regular expression.
|
||||
.SH ARGUMENTS
|
||||
.TP
|
||||
.I maxdepth
|
||||
Maximum depth (integer) to pass to
|
||||
.BR find (1)
|
||||
via
|
||||
.B \-maxdepth .
|
||||
Depth 1 means the current directory only, 2 includes its immediate
|
||||
subdirectories, and so on.
|
||||
.TP
|
||||
.I regex
|
||||
An extended POSIX regular expression used to filter which lines are
|
||||
considered before duplicate detection. If omitted, all non\-comment,
|
||||
non\-blank lines of length at least five are considered.
|
||||
.SH OPTIONS
|
||||
.TP
|
||||
.BI --maxdepth\ N " , " -d\ N
|
||||
Set maximum recursion depth. Default is 3.
|
||||
|
||||
.TP
|
||||
.BI --regex\ PATTERN " , " -r\ PATTERN
|
||||
Filter lines using the given POSIX extended regular expression.
|
||||
|
||||
.TP
|
||||
.BR --ignore-case " , " -i
|
||||
Case-insensitive matching.
|
||||
.SH BEHAVIOUR
|
||||
The command operates in three phases:
|
||||
|
||||
.IP 1. 3
|
||||
Find all regular files under the current directory up to
|
||||
.I maxdepth
|
||||
whose names either have no extension or end in
|
||||
.BR .zsh ,
|
||||
.BR .sh ,
|
||||
.BR .zlogin
|
||||
or
|
||||
.BR .symlink .
|
||||
|
||||
.IP 2. 3
|
||||
For each file, run
|
||||
.BR grep (1)
|
||||
with the given
|
||||
.I regex
|
||||
and optional case\-insensitive flag, then use
|
||||
.BR awk (1)
|
||||
to:
|
||||
.RS
|
||||
.IP \(bu 2
|
||||
discard comment lines (first non\-whitespace character
|
||||
.BR # ),
|
||||
.IP \(bu 2
|
||||
discard blank or whitespace\-only lines,
|
||||
.IP \(bu 2
|
||||
discard lines whose length is less than five characters,
|
||||
.IP \(bu 2
|
||||
normalise line endings and remove stray carriage returns and non\-breaking spaces.
|
||||
.RE
|
||||
|
||||
.IP 3. 3
|
||||
All remaining lines are grouped by their content. Any line that appears
|
||||
in more than one file (or more than once across all scanned files) is
|
||||
printed together with the list of file paths in which it occurs.
|
||||
|
||||
.SH OUTPUT
|
||||
For each duplicated line, output is of the form:
|
||||
.PP
|
||||
.nf
|
||||
==== Duplicate line: "export DOTFILES=\\"${DOTFILES:-$HOME/.dotfiles}\\"" ====
|
||||
./zlogin.symlink
|
||||
./zshrc.symlink
|
||||
|
||||
==== Duplicate line: "export outfile=\\"${outfile:-$HOME/zshrc-log.json}\\"" ====
|
||||
./zlogin.symlink
|
||||
./zshrc.symlink
|
||||
.fi
|
||||
.SH EXIT STATUS
|
||||
.TP
|
||||
.B 0
|
||||
Command completed successfully (whether or not any duplicates were found).
|
||||
.TP
|
||||
.B 1
|
||||
Usage error (missing
|
||||
.I maxdepth
|
||||
or invalid arguments).
|
||||
.SH EXAMPLES
|
||||
.TP
|
||||
Search up to depth 3 for any duplicated non\-comment lines:
|
||||
.PP
|
||||
.nf
|
||||
find_dupes 3
|
||||
.fi
|
||||
.TP
|
||||
Search up to depth 4, restricting to lines containing "export" (case\-sensitive):
|
||||
.PP
|
||||
.nf
|
||||
find_dupes 4 'export'
|
||||
.fi
|
||||
.TP
|
||||
Search up to depth 2, restricting to "export" lines case\-insensitively:
|
||||
.PP
|
||||
.nf
|
||||
find_dupes 2 'export' --ignore-case
|
||||
.fi
|
||||
.SH FILES
|
||||
.TP
|
||||
.I ~/.dotfiles/bin/find_dupes
|
||||
Autoloaded Zsh function implementing this command.
|
||||
.SH SEE ALSO
|
||||
.BR zsh (1),
|
||||
.BR grep (1),
|
||||
.BR awk (1),
|
||||
.BR find (1)
|
||||
Reference in New Issue
Block a user