archivos · Referencia de comando

`qzx findFiles`

Qué hace

Busca archivos con filtros avanzados de nombre, profundidad, tipo, tamaño, fecha y contenido.

Comando canónico: findFiles

Alias aceptados: Ninguno

Distingue mayúsculas: no

Incluido en el paquete publicado

Disponible en PyPI 0.2.2.0.2. La documentación corresponde al checkout alpha 0.2.2.0.2.

Seguridad y efectos

Solo lectura según la clasificación actual

Sin parámetro dry-run documentado

No invoca programas nativos según la clasificación

Sin uso de red documentado

No requiere elevación de forma inherente

Esta clasificación de seguridad se revisó contra el digest de implementación sha256:838ed7b792664fcef191241b58375a6fcac28b0d8244274a7937bbca2e243e41 el 2026-07-24.

Sintaxis exacta

qzx findFiles [search_path] [pattern] [recursive] [max_depth] [type] [size] [min_size] [max_size] [mtime] [newer_than] [older_than] [contains] [contains_regex] [case_sensitive] [exclude] [exclude_dir] [follow_symlinks] [sort_by] [reverse_sort] [format] [limit] --json

Parámetros

Nombre	Tipo	Obligatorio	Predeterminado	Descripción
search_path	str	No	"."	Path to start the search from
pattern	str	No	"*"	File name pattern to search for (supports glob syntax: *.txt, data-???.csv)
recursive	str	No	"-r"	Recursion level: -r/--recursive for unlimited depth, -rN/--recursiveN for N levels deep
max_depth	str	No	No declarado	Maximum directory depth to search (null for unlimited)
type	str	No	No declarado	Filter by type: "f" (files), "d" (directories), or "l" (links)
size	str	No	No declarado	Filter by size (e.g., +1M for >1MB, -500K for <500KB, 10K for exactly 10KB)
min_size	str	No	No declarado	Minimum file size in bytes or with KB/MB/GB suffix
max_size	str	No	No declarado	Maximum file size in bytes or with KB/MB/GB suffix
mtime	str	No	No declarado	Filter by modification time (e.g., +7 for >7 days old, -2 for <2 days old)
newer_than	str	No	No declarado	Files newer than specified date (YYYY-MM-DD) or "today", "yesterday"
older_than	str	No	No declarado	Files older than specified date (YYYY-MM-DD) or "today", "yesterday"
contains	str	No	No declarado	Only include files containing this text
contains_regex	str	No	No declarado	Only include files matching this regex pattern
case_sensitive	bool	No	false	Make content searches case sensitive (true/false)
exclude	str	No	No declarado	Exclude file/directory patterns (comma-separated: .bak,.tmp)
exclude_dir	str	No	No declarado	Exclude directory patterns (comma-separated: .git,.vscode)
follow_symlinks	bool	No	false	Follow symbolic links (true/false)
sort_by	str	No	"path"	Sort by: name, path, size, mtime (modification time), or none
reverse_sort	bool	No	false	Reverse the sorting order (true/false)
format	str	No	"full"	Output format: "full" (default), "name" (filename only), "detailed" (full details), "json", "csv"
limit	str	No	No declarado	Maximum number of results to return

Ejemplos de entrada

qzx findFiles . *.py

Find all Python files in current directory and subdirectories

qzx findFiles /src *.js false

Find all JavaScript files in /src without searching subdirectories

qzx findFiles . * true 2 f

Find all files up to 2 levels deep

qzx findFiles . *.txt null f +1M

Find all text files larger than 1MB

qzx findFiles . * null null null null null null -7

Find files modified within the last 7 days

qzx findFiles . *.log null null null null null today null

Find log files created or modified today

qzx findFiles . *.py null null null null null null null TODO

Find Python files containing the word "TODO"

qzx findFiles . * null null null null null null null null "def\s+\w+"

Find files containing function definitions using regex

qzx findFiles . * null null null null null null null null null false "*.tmp,*.bak"

Find all files excluding temp and backup files

qzx findFiles . * true null null null null null null null null null null .git,node_modules

Find all files excluding .git and node_modules directories

Para obtener la carga estructurada completa, añade --json: qzx findFiles [search_path] [pattern] [recursive] [max_depth] [type] [size] [min_size] [max_size] [mtime] [newer_than] [older_than] [contains] [contains_regex] [case_sensitive] [exclude] [exclude_dir] [follow_symlinks] [sort_by] [reverse_sort] [format] [limit] --json

Ejemplo de salida observada

Capturado con QZX 0.2.2.0.2 en Windows 11; código de salida 0. Los valores dependientes del host y la duración pueden variar.

Comando del ejemplo: qzx findFiles ../artifacts/qzx-evidence/find-files "*.txt" -r --format name --json

{
    "success": true,
    "message": "Found 2 items in '../artifacts/qzx-evidence/find-files', total size: 13.00 B",
    "search_path": "../artifacts/qzx-evidence/find-files",
    "pattern": "*.txt",
    "recursive": "unlimited",
    "count": 2,
    "total_size": 13,
    "total_size_readable": "13.00 B",
    "results": [
        "alpha.txt",
        "beta.txt"
    ],
    "meta": {
        "command": "findFiles",
        "duration_ms": 1.49,
        "schema_version": 1
    }
}

Ver el contrato de resultado JSON

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
        "success",
        "message"
    ],
    "properties": {
        "success": {
            "type": "boolean"
        },
        "message": {
            "type": "string"
        },
        "count": [],
        "error": {
            "type": "string"
        },
        "pattern": [],
        "recursive": [],
        "results": [],
        "search_path": [],
        "total_size": [],
        "total_size_readable": [],
        "traceback": []
    },
    "additionalProperties": true
}

Errores y límites

El contrato público exige success=false y un message descriptivo en fallos. Este catálogo aún no declara una taxonomía de errores específica para cada comando; revisa el resultado y no infieras códigos inexistentes.

QZX está en alpha. Dependencias opcionales, permisos y capacidades del host pueden cambiar el resultado.

Flujo de evidencia: capturada y validada por digest.

Evidencia y procedencia

Implementación: src/qzx/commands/file/find_files.py
Pruebas: tests/test_file_commands/test_find_files.py
Canal de documentación: Documentación de desarrollo 0.2.2.0.2 · main · sha256:319b16857a87636ebc3b89734cc040a737bb56194464fca33ce73bdae2043096
Disponibilidad: 0.2.2.0.2 o anterior

Sigue explorando

Estos comandos también pertenecen a la categoría de archivos. Compáralos para elegir la operación que mejor resuelva tu tarea.

Explorar todos los comandos de QZX