cloc: contador de líneas de código, instalación y uso
Heredas un proyecto y quieres saber cuánto ocupa y en qué lenguajes está escrito. Contar a mano es imposible, y wc -l mezcla código, comentarios y líneas vacías.
cloc es como el contador de personas que usan en la puerta de un evento, pero con criterio: no solo cuenta cuántas entran, también las separa por grupos. Te dice cuántas líneas son código de verdad, cuántas comentarios y cuántas están en blanco, lenguaje a lenguaje.
Instalar cloc: npm, Ubuntu, macOS y Windows
cloc es un script de Perl. Los gestores de paquetes lo instalan con todo lo necesario:
sudo apt install cloc # Debian, Ubuntu
sudo dnf install cloc # Fedora
sudo pacman -S cloc # Arch
sudo pkg install cloc # FreeBSD
brew install cloc # macOS con Homebrew
sudo port install cloc # macOS con MacPorts
npm install -g cloc # con Node.js, en cualquier sistema
npx cloc . # sin instalar, con Node.js (necesita Perl)
En Windows:
winget install AlDanial.Cloc # winget
choco install cloc # Chocolatey
scoop install cloc # Scoop
El propio README avisa de que la instalación con winget puede fallar. Si te pasa, usa otra opción o descarga el ejecutable de la página de versiones.
Contar las líneas de un proyecto
Desde la carpeta del proyecto:
cloc .
Este es el resultado, con cloc 1.74, sobre una carpeta con tres programas en COBOL:
6 text files.
6 unique files.
3 files ignored.
github.com/AlDanial/cloc v 1.74 T=0.03 s (108.7 files/s, 11158.6 lines/s)
-------------------------------------------------------------------------------
Language files blank comment code
-------------------------------------------------------------------------------
COBOL 3 34 16 258
-------------------------------------------------------------------------------
SUM: 3 34 16 258
-------------------------------------------------------------------------------
| Columna | Qué cuenta |
|---|---|
files |
Ficheros de ese lenguaje |
blank |
Líneas vacías |
comment |
Líneas que solo tienen comentarios |
code |
Líneas con código. Es el dato que suele interesar |
Comandos útiles
cloc --vcs=git # solo los ficheros que sigue Git (ignora lo que está en .gitignore)
cloc --exclude-dir=node_modules,dist . # salta carpetas que no son tu código
cloc --by-file . # una línea por fichero en vez de por lenguaje
cloc --json . # salida en JSON, para scripts o CI
cloc --diff v1/ v2/ # qué se añadió, cambió o borró entre dos versiones
Un ejemplo completo, con cloc 2.10
Para ver la diferencia entre las opciones, se ha preparado un proyecto de prueba pequeño, una tienda con Git:
tienda/
├── .gitignore (ignora node_modules/ y build/)
├── src/main/kotlin/Carrito.kt (13 líneas)
├── web/app.js (8 líneas)
├── web/index.html (8 líneas)
├── web/correo.tmpl (2 líneas, una plantilla)
├── node_modules/libreria/ (40 ficheros .js de una dependencia)
└── build/ (5 ficheros .js generados)
Primero, sin opciones:
cloc .
github.com/AlDanial/cloc v 2.10 T=0.02 s (2114.6 files/s, 6784.2 lines/s)
-------------------------------------------------------------------------------
Language files blank comment code
-------------------------------------------------------------------------------
JavaScript 46 2 1 130
Kotlin 1 3 2 8
HTML 1 0 1 7
-------------------------------------------------------------------------------
SUM: 48 5 4 145
-------------------------------------------------------------------------------
Según esto, la tienda es casi toda JavaScript. No es verdad: 45 de esos 46 ficheros son la dependencia y lo generado. Ahora, contando solo lo que sigue Git:
cloc --vcs=git
github.com/AlDanial/cloc v 2.10 T=0.06 s (51.6 files/s, 498.7 lines/s)
-------------------------------------------------------------------------------
Language files blank comment code
-------------------------------------------------------------------------------
Kotlin 1 3 2 8
HTML 1 0 1 7
JavaScript 1 2 1 5
-------------------------------------------------------------------------------
SUM: 3 5 4 20
-------------------------------------------------------------------------------
De 145 a 20 líneas de código. cloc --exclude-dir=node_modules,build . da el mismo resultado sin depender de Git. Para comparar, wc -l sobre los ficheros de Git suma 33 líneas: mezcla código, comentarios, líneas en blanco y el propio .gitignore.
Qué ha cambiado en el último commit
Con --git --diff, cloc compara dos commits. Tras añadir una función al carrito y un comentario al final de una línea de app.js:
cloc --git --diff HEAD~1 HEAD
github.com/AlDanial/cloc v 2.10 T=0.09 s (21.5 files/s, 193.2 lines/s)
-------------------------------------------------------------------------------
Language files blank comment code
-------------------------------------------------------------------------------
Kotlin
same 0 0 2 8
modified 1 0 0 0
added 0 1 0 1
removed 0 0 0 0
JavaScript
same 0 0 1 4
modified 1 0 0 1
added 0 0 0 0
removed 0 0 0 0
-------------------------------------------------------------------------------
SUM:
same 0 0 3 12
modified 2 0 0 1
added 0 1 0 1
removed 0 0 0 0
-------------------------------------------------------------------------------
Se lee por filas: en Kotlin se ha añadido una línea de código y una en blanco; en JavaScript, una línea de código ha cambiado (modified), porque ahora lleva un comentario al final. La columna files de modified cuenta los ficheros tocados.
Para un script o para la integración continua
Con --json (y --quiet, que quita los mensajes de progreso), la salida se puede leer desde otro programa:
cloc --vcs=git --json --quiet
{"header" : {
"cloc_url" : "github.com/AlDanial/cloc",
"cloc_version" : "2.10",
"elapsed_seconds" : 0.065371036529541,
"n_files" : 3,
"n_lines" : 31,
"files_per_second" : 45.8918836118547,
"lines_per_second" : 474.216130655832},
"Kotlin" :{
"nFiles": 1,
"blank": 4,
"comment": 2,
"code": 9},
"HTML" :{
"nFiles": 1,
"blank": 0,
"comment": 1,
"code": 7},
"JavaScript" :{
"nFiles": 1,
"blank": 2,
"comment": 1,
"code": 5},
"SUM": {
"blank": 6,
"comment": 4,
"code": 21,
"nFiles": 3} }
Es la salida después del commit de la función nueva: por eso Kotlin tiene ya 9 líneas de código.
Errores frecuentes
1. Contar las dependencias
Es el caso de cloc . de arriba: node_modules, vendor, build o dist inflan el resultado y cambian hasta el lenguaje principal. Usa --vcs=git en un repositorio, o --exclude-dir si no lo es.
2. --vcs=git fuera de un repositorio
Si ejecutas cloc --vcs=git en una carpeta que no es un repositorio, Git se queja dos veces y cloc no cuenta nada:
fatal: not a git repository (or any of the parent directories): .git
fatal: not a git repository (or any of the parent directories): .git
Lo engañoso es que el código de salida es 0, como si todo hubiera ido bien. En un script, no te fíes de él: comprueba antes que estás dentro del repositorio (git rev-parse --is-inside-work-tree).
3. Ficheros que no cuenta sin avisar
En el ejemplo, correo.tmpl no aparece en ninguna tabla: cloc no conoce la extensión .tmpl y la ignora. Para saber qué se ha dejado fuera y por qué, pide la lista:
cloc --vcs=git --quiet --ignored=ignorados.txt
cat ignorados.txt
./.gitignore: listed in $Not_Code_Extension{gitignore}
./web/correo.tmpl: language unknown (#3)
Si sabes a qué lenguaje se parece, díselo con --force-lang=lenguaje,extensión. La salida es del estado final del proyecto, con el commit de la función nueva, como la del JSON:
cloc --vcs=git --force-lang=HTML,tmpl
github.com/AlDanial/cloc v 2.10 T=0.06 s (67.5 files/s, 557.2 lines/s)
-------------------------------------------------------------------------------
Language files blank comment code
-------------------------------------------------------------------------------
HTML 2 0 1 9
Kotlin 1 4 2 9
JavaScript 1 2 1 5
-------------------------------------------------------------------------------
SUM: 4 6 4 23
-------------------------------------------------------------------------------
Con cloc --show-lang ves todos los lenguajes que reconoce y sus extensiones.
4. Una versión más antigua de la que crees
Como se explica arriba, los paquetes de algunas distribuciones van por detrás, y en npm basta con fijar una versión sin sufijo ([email protected]) o un rango como ^2 para acabar con cloc 1.94 o 1.96, de 2022. Si una opción del README no funciona, mira primero cloc --version.
5. cloc: command not found
No está instalado o no está en el PATH. Si lo instalaste con npm de forma global, comprueba que la carpeta de binarios globales de npm está en el PATH; si descargaste el .pl, ejecútalo con perl cloc-2.10.pl o dale permisos con chmod +x.
Más líneas no es más valor.
Cuándo no usar cloc
- Para medir la productividad de nadie. Borrar código que sobra es a menudo el mejor trabajo del día, y cloc lo mostraría como un número que baja. En el ejemplo del diff, una línea «modificada» puede ser un arreglo importante o un comentario.
- Para comparar proyectos en lenguajes distintos. Diez líneas de Kotlin y diez de COBOL no hacen lo mismo. cloc cuenta líneas, no funcionalidad.
- Para decidir dónde está la complejidad. Un fichero largo y sencillo puede ser más fácil de mantener que uno corto lleno de condiciones. Para eso, mira la complejidad ciclomática (enlace abajo) o
scc, que la estima. - En repositorios enormes, si tienes prisa. cloc es un script de Perl; scc y tokei, de la tabla de abajo, son más rápidos.
Sí sirve para hacerte una idea del tamaño de un proyecto, ver qué lenguajes usa o seguir cuánto crece con el tiempo.
Ejercicio de cinco minutos
- En un proyecto tuyo con Git, ejecuta
cloc .ycloc --vcs=gity compara el total decode. La diferencia es lo que no es tu código. - Genera la lista de ignorados con
--ignored=ignorados.txt. ¿Hay algún fichero tuyo con «language unknown»? Cuéntalo con--force-lang. - Ejecuta
cloc --git --diff HEAD~10 HEADy mira cuánto código se ha añadido y cuánto se ha borrado en los diez últimos commits.
Alternativas
cloc es lento en repositorios enormes porque es un script de Perl. El README enumera otros contadores; entre ellos, scc y tokei son más rápidos según sus propios proyectos. Los dos son de código abierto y siguen mantenidos en 2026:
| Herramienta | Escrita en | Qué añade |
|---|---|---|
| scc | Go | Además de contar, estima la complejidad de cada fichero y el coste con el modelo COCOMO |
| tokei | Rust | Rápida y con salida en JSON, YAML o CBOR para usarla en scripts |
Para un proyecto normal, cloc va de sobra y tiene una ventaja práctica: está en los gestores de paquetes de casi todos los sistemas, como has visto arriba.
Para saber más
Si quieres medir algo más útil que el tamaño, mira la complejidad ciclomática, que indica lo difícil que es probar y mantener cada función. Y si te preocupa el código que crece sin control, empieza por qué es la deuda técnica. Un fichero con muchas más líneas que el resto puede ser la pista de un God Object, una clase que lo hace todo.
Fuentes
- README oficial de cloc y versión 2.10, publicada el 4 de julio de 2026 según la API de GitHub: métodos de instalación, aviso sobre winget, opciones, licencia GPL-2.0 y alternativas (scc y tokei).
- Repositorios de scc (v4.1.0, septiembre de 2026) y tokei (v15.0.0, septiembre de 2026). La antigua cloc.sourceforge.net enlaza al repositorio de GitHub.
- Ejecutado el 7 de noviembre de 2026 en Ubuntu 26.04:
cloc-2.10.plcon Perl 5.40.1 (cloc .,--vcs=git,--exclude-dir,--diff) ynpx [email protected]con Node 24.21 (--by-file,--json). Ese paquete sin sufijo es de 2022 e informa de la versión 1.94. La versión del paquete de Ubuntu (2.06) se consultó conapt-cache policy cloc. La salida de COBOL es la del artículo original (cloc 1.74). - Ejemplo completo y errores frecuentes: ejecutados el 11 de noviembre de 2026 con
cloc-2.10.pl(descargado de la página de versiones de GitHub), Perl 5.40.1 y Git 2.47.3, en un contenedor Dockerdebian:stable(Debian 13.7), sobre un proyecto de prueba creado para el artículo:cloc .,--vcs=git,--exclude-dir,--git --diff,--json --quiet,--ignored,--force-lang,--show-lang,--vcs=gitfuera de un repositorio (con su código de salida) ywc -l. Ese mismo día se descargaron connpm packlos paquetes de npm[email protected](etiquetalatest, publicado el 22 de octubre de 2026),[email protected](5 de julio de 2022) y[email protected](29 de diciembre de 2022), y su script, ejecutado con--version, da 2.10, 1.94 y 1.96. Que scc y tokei sean más rápidos lo dicen sus READMEs («Goal is to be the fastest code counter possible» y «Tokei is very fast»); el README de cloc los incluye en su lista «Other Counters», junto a otros nueve.