fast-folder-cli

⚡ fast-folder-cli

Encuentra cualquier carpeta de tu PC en segundos, directamente desde la terminal.

fast-folder-cli es una herramienta de línea de comandos escrita en Go que recorre el disco de forma concurrente para localizar carpetas por nombre, pensada para reemplazar la lenta búsqueda del Explorador de archivos de Windows.

> fast-folder-cli -n proyecto

Buscando "proyecto" en C:\Users\usuario (ocultas/sistema: excluidas)

  [1] C:\Users\usuario\Documents\Proyecto-Final
  [2] C:\Users\usuario\Desktop\escuela\mi-proyecto
  [3] C:\Users\usuario\source\repos\proyecto-api

────────────────────────────────────────────────────────────────
Resultados : 3 carpetas encontradas
Analizadas : 27,972 carpetas
Tiempo     : 854 ms

📌 El problema

Buscar una carpeta con el cuadro de búsqueda del Explorador de Windows suele ser una experiencia frustrante:

• Depende del índice de Windows Search. Fuera de las ubicaciones indexadas (otras unidades, AppData, ProgramData, carpetas de proyectos...) el Explorador recorre el disco de forma secuencial y los resultados aparecen a cuentagotas.
• Busca de más. Examina archivos, contenido y propiedades aunque solo quieras una carpeta.
• No es automatizable. No puedes usarlo desde un script ni encadenarlo con otras herramientas.
• Las alternativas en consola son lentas. dir /s /b /ad y Get-ChildItem -Recurse recorren el árbol en un único hilo.

✅ La solución

📊 Rendimiento

Búsqueda de una carpeta en todo el perfil de usuario (%USERPROFILE%, incluyendo carpetas ocultas: ~149,000 carpetas), en Windows 11 con un procesador de 8 núcleos y SSD:

Ambas encontraron las mismas 4 carpetas, pero fast-folder-cli fue ~8.7 veces más rápido. Sin carpetas ocultas (el modo por defecto) el mismo perfil se recorre en menos de 1 segundo. Los tiempos dependen del disco y de la caché del sistema de archivos: la segunda búsqueda suele ser más rápida.

🛠️ Instalación

Requisitos

• Windows 10 u 11 (también compila en Linux y macOS, con funciones limitadas).

• Go 1.23 o superior, solo si vas a usar go install o compilar el código. Con winget:

  winget install GoLang.Go
  

Descargar el ejecutable (sin instalar Go)

Descarga el .exe de la última versión:

Renómbralo a fast-folder-cli.exe y sigue los pasos de Agregar al PATH.

⚠️ Los ejecutables no están firmados digitalmente, así que Windows SmartScreen o tu antivirus pueden mostrar una advertencia la primera vez. Para comprobar que el archivo es el original, compara Get-FileHash .\fast-folder-cli.exe con el valor de checksums.txt publicado en la versión; después puedes quitar la marca de descarga con Unblock-File .\fast-folder-cli.exe.

Instalación rápida con go install

go install github.com/AnthonyCZ6/fast-folder-cli@latest

Go descarga, compila e instala el ejecutable en %USERPROFILE%\go\bin, carpeta que el instalador de Go ya agrega al PATH: no hace falta clonar el repositorio ni el paso Agregar al PATH.

Compilar el ejecutable .exe

git clone https://github.com/AnthonyCZ6/fast-folder-cli.git
cd fast-folder-cli
go build -trimpath -ldflags "-s -w -X main.version=1.0.0" -o fast-folder-cli.exe .

Compilación cruzada desde Linux o macOS (o para equipos Windows ARM):

GOOS=windows GOARCH=amd64 go build -trimpath -ldflags "-s -w" -o fast-folder-cli.exe .
GOOS=windows GOARCH=arm64 go build -trimpath -ldflags "-s -w" -o fast-folder-cli-arm64.exe .

Agregar al PATH de Windows

Así podrás ejecutar fast-folder-cli desde cualquier carpeta y cualquier terminal.

Opción A — PowerShell (recomendada, no requiere administrador)

Desde la carpeta donde está fast-folder-cli.exe (descargado o compilado):

$dest = "$env:LOCALAPPDATA\Programs\fast-folder-cli"
New-Item -ItemType Directory -Force -Path $dest | Out-Null
Copy-Item .\fast-folder-cli.exe $dest -Force

$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
if (($userPath -split ";") -notcontains $dest) {
    [Environment]::SetEnvironmentVariable("Path", "$userPath;$dest", "User")
}

Opción B — Interfaz gráfica

1. Copia fast-folder-cli.exe a una carpeta permanente, por ejemplo C:\Users\<usuario>\AppData\Local\Programs\fast-folder-cli.
2. Pulsa Win + R, escribe SystemPropertiesAdvanced y pulsa Enter.
3. Haz clic en Variables de entorno....
4. En Variables de usuario, selecciona Path → Editar → Nuevo y pega la ruta de la carpeta.
5. Acepta todas las ventanas.

Verificar la instalación

Cierra y vuelve a abrir la terminal (el PATH solo se lee al iniciarla) y ejecuta:

fast-folder-cli --version

💡 Atajo: renombra el ejecutable a ff.exe o crea un alias en tu perfil de PowerShell (notepad $PROFILE): Set-Alias ff fast-folder-cli

🚀 Uso

fast-folder-cli -n <término> [-p <ruta>] [-a] [-o]
fast-folder-cli <término> [opciones]

Banderas

Las banderas pueden escribirse en cualquier orden, antes o después del término, y con = o espacio: --name=proyecto equivale a --name proyecto.

Ejemplos

# Buscar en tu perfil de usuario
fast-folder-cli -n proyecto

# Término como argumento posicional (con espacios, entre comillas)
fast-folder-cli "mis documentos escolares"

# Buscar en AppData incluyendo carpetas ocultas
fast-folder-cli -n discord -p %APPDATA% -a

# Buscar en otra unidad y abrir el primer resultado en el Explorador
fast-folder-cli -n "tesis*" -p D: -o

# Buscar datos de aplicaciones en ProgramData
fast-folder-cli --name nvidia --path %PROGRAMDATA% --all

# Guardar los resultados en un archivo
fast-folder-cli -n node_modules -p C:\dev > resultados.txt

Reglas de coincidencia

Las búsquedas no distinguen mayúsculas de minúsculas, igual que Windows.

Sin comodines, el término puede aparecer en cualquier parte del nombre. Con comodines (*, ?, [ ]) el patrón debe cubrir el nombre completo de la carpeta.

Variables de entorno y rutas especiales

Funciona con cualquier variable definida en el sistema. PowerShell no expande la sintaxis %VAR%, así que fast-folder-cli la resuelve por su cuenta; en PowerShell también puedes usar la sintaxis nativa (-p $env:APPDATA).

Carpetas ocultas y de sistema

Por defecto se omiten (ni se muestran ni se recorren):

• Carpetas con el atributo Oculto o Sistema de Windows (AppData, $Recycle.Bin, System Volume Information, ...).
• Carpetas cuyo nombre empieza por punto (.git, .vscode, .cache, ...).

Usa -a / --all para incluirlas. La carpeta raíz indicada con --path siempre se recorre, aunque esté oculta: -p %APPDATA% funciona sin --all.

Códigos de salida

Útiles para scripts, siguiendo la convención de grep:

⚙️ Cómo funciona

             ┌────────────────── semáforo (4 × núcleos) ──────────────────┐
  raíz ──►  walk(dir) ──► ¿hay un slot libre? ──sí──► nueva goroutine: walk(subdir)
                                   │
                                   └──no──► walk(subdir) en la goroutine actual

1. Concurrencia acotada sin interbloqueos. Cada subcarpeta se entrega a una goroutine nueva si hay capacidad libre en el semáforo; si no, la goroutine actual la procesa en profundidad. Nunca hay más goroutines activas que el límite y ninguna se queda bloqueada esperando a otra.
2. Mínimas llamadas al sistema. Los atributos (oculto, sistema, reparse point) se leen de los datos que Windows ya devuelve al listar el directorio, sin consultas adicionales por carpeta. Las entradas no se ordenan, ahorrando trabajo en carpetas grandes.
3. Errores sin interrupciones. Un "Acceso denegado" solo incrementa el contador sin acceso; el resto del árbol se sigue recorriendo.
4. Resultados en tiempo real. Cada coincidencia se imprime en cuanto se encuentra; la salida se agrupa en un búfer que se vacía cuando no hay más resultados pendientes, para no ralentizar la consola cuando hay miles de coincidencias.
5. Enlaces seguros. Las uniones heredadas de Windows (por ejemplo AppData\Local\Application Data, que apunta a sí misma) provocarían un bucle infinito. Los enlaces se muestran si coinciden, pero nunca se recorren. Las carpetas de OneDrive sí se recorren con normalidad.

📁 Estructura del proyecto

fast-folder-cli/
├── main.go                        # Punto de entrada
├── internal/
│   ├── cli/                       # Banderas, formato de salida y colores de consola
│   ├── search/                    # Motor de búsqueda concurrente y coincidencia de nombres
│   ├── pathutil/                  # Resolución de %VARIABLES%, ~ y unidades
│   └── explorer/                  # Apertura de carpetas en el Explorador de Windows
├── go.mod
├── LICENSE
└── README.md

🧪 Desarrollo

go test ./...     # pruebas unitarias (incluye pruebas específicas de Windows: atributos y junctions)
go vet ./...      # análisis estático
gofmt -l .        # comprobar formato

🤝 Contribuir

1. Haz un fork del repositorio y crea una rama: git checkout -b feat/mi-mejora.
2. Asegúrate de que go test ./... y go vet ./... pasan.
3. Usa Conventional Commits en tus mensajes (feat:, fix:, docs:, refactor:...).
4. Abre un pull request describiendo el cambio.

📄 Licencia

Distribuido bajo la licencia MIT. Consulta el archivo LICENSE para más detalles.

📬 Contacto

Anthony — autor y mantenedor

• GitHub: @AnthonyCZ6
• Correo: 20243ds055@utez.edu.mx
• Reporta errores o propone mejoras en Issues.

Si esta herramienta te ahorra tiempo, ¡considera darle una ⭐ al repositorio!