1cloc(1)                          User Commands                         cloc(1)
2
3
4

NAME

6       cloc - Count, or compute differences of, lines of source code and
7       comments.
8

SYNOPSIS

10         cloc [options] <FILE|DIR> ...
11

DESCRIPTION

13       Count, or compute differences of, physical lines of source code in the
14       given files (may be archives such as compressed tarballs or zip files,
15       or git commit hashes or branch names) and/or recursively below the
16       given directories.  It is written entirely in Perl, using only modules
17       from the standard distribution.
18

OPTIONS

20   Input Options
21       To count standard input, use the special filename - and either
22       --stdin-name=FILE to tell cloc the name of the file being piped in, or
23       --force-lang=LANG to apply the LANG counter to all input.
24
25       --extract-with=CMD
26           This option is only needed if cloc is unable to figure out how to
27           extract the contents of the input file(s) by itself. Use CMD to
28           extract binary archive files (e.g.: .tar.gz, .zip, .Z). Use the
29           literal '>FILE<' as a stand-in for the actual file(s) to be
30           extracted. For example, to count lines of code in the input files
31           gcc-4.2.tar.gz perl-5.8.8.tar.gz on Unix use:
32
33               --extract-with='gzip -dc >FILE< | tar xf -
34
35           or, if you have GNU tar:
36
37               --extract-with='tar zxf >FILE<'
38
39           and on Windows, use, for example:
40
41               --extract-with="\"c:\Program Files\WinZip\WinZip32.exe\" -e -o >FILE<
42
43       --list-file=FILE
44           Take the list of file and/or directory names to process from FILE,
45           which has one file/directory name per line.  Only exact matches are
46           counted; relative path names will be resolved starting from the
47           directory where cloc is invoked.  Set FILE to - to read file names
48           from a STDIN pipe.  See also --exclude-list-file, --config.
49
50       --diff-list-file=FILE
51           Take the pairs of file names to be diff'ed from FILE, whose format
52           matches the output of --diff-alignment.  (Run with that option to
53           see a sample.)  The language identifier at the end of each line is
54           ignored.  This enables --diff mode and by-passes file pair
55           alignment logic.  See also --config.
56
57       --vcs=VCS
58           Invoke a system call to VCS to obtain a list of files to work on.
59           If VCS is 'git', then will invoke 'git ls-files' to get a file list
60           and 'git submodule status' to get a list of submodules whose
61           contents will be ignored.  See also --git which accepts git commit
62           hashes and branch names.  If VCS is 'svn' then will invoke 'svn
63           list -R'.  The primary benefit is that cloc will then skip files
64           explicitly excluded by the versioning tool in question, ie, those
65           in .gitignore or have the svn:ignore property.  Alternatively VCS
66           may be any system command that generates a list of files.  Note:
67           cloc must be in a directory which can read the files as they are
68           returned by VCS.  cloc will not download files from remote
69           repositories.  'svn list -R' may refer to a remote repository to
70           obtain file names (and therefore may require authentication to the
71           remote repository), but the files themselves must be local.
72           Setting VCS to 'auto' selects between 'git' and 'svn' (or neither)
73           depending on the presence of a .git or .svn subdirectory below the
74           directory where cloc is invoked.
75
76       --unicode
77           Check binary files to see if they contain Unicode expanded ASCII
78           text.  This causes performance to drop noticeably.
79
80   Processing Options
81       --autoconf
82           Count .in files (as processed by GNU autoconf) of recognized
83           languages.  See also --no-autogen.
84
85       --by-file
86           Report results for every source file encountered.
87
88       --by-file-by-lang
89           Report results for every source file encountered in addition to
90           reporting by language.
91
92       --config FILE
93           Read command line switches from FILE instead of the default
94           location of ~/.config/cloc/options.txt.  The file should contain
95           one switch, along with arguments (if any), per line.  Blank lines
96           and lines beginning with '#' are skipped.  Options given on the
97           command line take priority over entries read from the file.  If a
98           directory is also given with any of these switches: --list-file,
99           --exclude-list-file, --read-lang-def, --force-lang-def,
100           --diff-list-file and a config file exists in that directory, it
101           will take priority over ~/.config/cloc/options.txt.
102
103       --count-and-diff SET1 SET2
104           First perform direct code counts of source file(s) of SET1 and SET2
105           separately, then perform a diff of these.  Inputs may be pairs of
106           files, directories, or archives.  If --out or --report-file is
107           given, three output files will be created, one for each of the two
108           counts and one for the diff.  See also --diff, --diff-alignment,
109           --diff-timeout, --ignore-case, --ignore-whitespace.
110
111       --diff SET1 SET2
112           Compute differences in code and comments between source file(s) of
113           SET1 and SET2.  The inputs may be pairs of files, directories, or
114           archives.  Use --diff-alignment to generate a list showing which
115           file pairs where compared.  See also --count-and-diff,
116           --diff-alignment, --diff-timeout, --ignore-case,
117           --ignore-whitespace.
118
119       --diff-timeout N
120           Ignore files which take more than N seconds to process.  Default is
121           10 seconds.  Setting N to 0 allows unlimited time.  (Large files
122           with many repeated lines can cause Algorithm::Diff::sdiff() to take
123           hours.)
124
125       --docstring-as-code
126           cloc considers docstrings to be comments, but this is not always
127           correct as docstrings represent regular strings when they appear on
128           the right hand side of an assignment or as function arguments.
129           This switch forces docstrings to be counted as code.
130
131       --follow-links
132           [Unix only] Follow symbolic links to directories (sym links to
133           files are always followed).
134
135       --force-lang=LANG[,EXT]
136           Process all files that have a EXT extension with the counter for
137           language LANG. For example, to count all .f files with the Fortran
138           90 counter (which expects files to end with .f90) instead of the
139           default Fortran 77 counter, use:
140
141                   --force-lang="Fortran 90",f
142
143           If EXT is omitted, every file will be counted with the LANG
144           counter.  This option can be specified multiple times (but that is
145           only useful when EXT is given each time). See also --script-lang,
146           --lang-no-ext.
147
148       --force-lang-def=FILE
149           Load language processing filters from FILE, then use these filters
150           instead of the built-in filters.  Note:  languages which map to the
151           same file extension (for example: MATLAB/Objective-C/MUMPS;
152           Pascal/PHP; Lisp/OpenCL; Lisp/Julia; Perl/Prolog) will be ignored
153           as these require additional processing that is not expressed in
154           language definition files.  Use --read-lang-def to define new
155           language filters without replacing built-in filters (see also
156           --write-lang-def, --write-lang-def-incl-dup).
157
158       --git
159           Forces the inputs to be interpreted as git targets (commit hashes,
160           branch names, et cetera) if these are not first identified as file
161           or directory names.  This option overrides the --vcs=git logic if
162           this is given; in other words, --git gets its list of files to work
163           on directly from git using the hash or branch name rather than from
164           'git ls-files'.  This option can be used with --diff to perform
165           line count diffs between git commits, or between a git commit and a
166           file, directory, or archive.  Use -v/--verbose to see the git
167           system commands cloc issues.
168
169       --git-diff-rel
170           Same as --git --diff, or just --diff if the inputs are recognized
171           as git targets.  Only files which have changed in either commit are
172           compared.
173
174       --git-diff-all
175           Git diff strategy #2:  compare all files in the repository between
176           the two commits.
177
178       --ignore-whitespace
179           Ignore horizontal white space when comparing files with --diff.
180           See also --ignore-case.
181
182       --ignore-case
183           Ignore changes in case within file contents; consider upper- and
184           lowercase letters equivalent when comparing files with --diff.  See
185           also --ignore-whitespace.
186
187       --ignore-case-ext
188           Ignore case of file name extensions.  This will cause problems
189           counting some languages (specifically, .c and .C are associated
190           with C and C++; this switch would count .C files as C rather than
191           C++ on *nix operating systems).  File name case insensitivity is
192           always true on Windows.
193
194       --lang-no-ext=LANG
195           Count files without extensions using the LANG counter.  This option
196           overrides internal logic for files without extensions (where such
197           files are checked against known scripting languages by examining
198           the first line for "#!").  See also --force-lang, --script-lang.
199
200       --max-file-size=MB
201           Skip files larger than "MB" megabytes when traversing directories.
202           By default, "MB"=100.  cloc's memory requirement is roughly twenty
203           times larger than the largest file so running with files larger
204           than 100 MB on a computer with less than 2 GB of memory will cause
205           problems.  Note:  this check does not apply to files explicitly
206           passed as command line arguments.
207
208       --no-autogen[=list]
209           Ignore files generated by code-production systems such as GNU
210           autoconf.  To see a list of these files (then exit), run with
211           --no-autogen list See also --autoconf.
212
213           ==item --original-dir
214
215           Only effective in combination with --strip-comments.  Write the
216           stripped files to the same directory as the original files.
217
218       --read-binary-files
219           Process binary files in addition to text files. This is usually a
220           bad idea and should only be attempted with text files that have
221           embedded binary data.
222
223       --read-lang-def=FILE
224           Load new language processing filters from FILE and merge them with
225           those already known to cloc.  If FILE defines a language cloc
226           already knows about, cloc's definition will take precedence.  Use
227           --force-lang-def to over-ride cloc's definitions.  (see also
228           --write-lang-def).
229
230       --script-lang=LANG,S
231           Process all files that invoke "S" as a "#!" scripting language with
232           the counter for language LANG. For example, files that begin with
233           "#!/usr/local/bin/perl5.8.8" will be counted with the Perl counter
234           by using
235
236                   --script-lang=Perl,perl5.8.8
237
238           The language name is case insensitive but the name of the script
239           language executable, "S", must have the right case. This option can
240           be specified multiple times. See also --force-lang.
241
242       --sdir=DIR
243           Use DIR as the scratch directory instead of letting File::Temp
244           chose the location. Files written to this location are not removed
245           at the end of the run (as they are with File::Temp).
246
247       --skip-leading=N[,ext]
248            Skip the first <N> lines of each file.  If a
249           comma separated list of extensions is also given,
250           only skip lines from those file types.  Example:
251
252                   --skip-leading=10,cpp,h
253
254           will skip the first ten lines of *.cpp and *.h files.  This is
255           useful for ignoring boilerplate text.
256
257       --skip-uniqueness
258           Skip the file uniqueness check. This will give a performance boost
259           at the expense of counting files with identical contents multiple
260           times (if such duplicates exist).
261
262       --stat
263           Some file systems (AFS, CD-ROM, FAT, HPFS, SMB) do not have
264           directory 'nlink' counts that match the number of its
265           subdirectories.  Consequently cloc may undercount or completely
266           skip the contents of such file systems.  This switch forces
267           File::Find to stat directories to obtain the correct count.  File
268           search spead will decrease.  See also --follow-links.
269
270       --stdin-name=FILE
271           Count lines streamed via STDIN as if they came from a file named
272           FILE.
273
274       --strip-comments=EXT
275           For each file processed, write to the current directory a version
276           of the file which has blank and commented lines removed (in-line
277           comments persist). The name of each stripped file is the original
278           file name with ".EXT" appended to it. It is written to the current
279           directory unless --original-dir is on.
280
281       --strip-str-comments
282           Replace comment markers embedded in strings with 'xx'.  This
283           attempts to work around a limitation in Regexp::Common::Comment
284           where comment markers embedded in strings are seen as actual
285           comment markers and not strings, often resulting in a 'Complex
286           regular subexpression recursion limit' warning and incorrect
287           counts.  There are two disadvantages to using this switch:  1/code
288           count performance drops, and 2/code generated with --strip-comments
289           will contain different strings where ever embedded comments are
290           found.
291
292       --sum-reports
293           Input arguments are report files previously created with the
294           --report-file option. Makes a cumulative set of results containing
295           the sum of data from the individual report files.
296
297           --timeout=N
298
299           Ignore files which take more than <N> seconds to process at any of
300           the language's filter stages.  The default maximum number of
301           seconds spent on a filter stage is the number of lines in the file
302           divided by one thousand.  Setting N to 0 allows unlimited time.
303           See also --diff-timeout.
304
305       --processes=NUM
306           [Available only on systems with a recent version of the
307           Parallel::ForkManager module.  Not available on Windows.] Sets the
308           maximum number of cores that cloc uses.  The default value of 0
309           disables multiprocessing.
310
311       --unix
312           Over-ride the operating system detection logic and run in UNIX
313           mode.  See also --windows, --show-os.
314
315       --use-sloccount
316           If SLOCCount is installed, use its compiled executables c_count,
317           java_count, pascal_count, php_count, and xml_count instead of
318           cloc's counters.  SLOCCount's compiled counters are substantially
319           faster than cloc's and may give a performance improvement when
320           counting projects with large files.  However, these cloc-specific
321           features will not be available: --diff, --count-and-diff,
322           --strip-comments, --unicode.
323
324       --windows
325           Over-ride the operating system detection logic and run in Microsoft
326           Windows mode.  See also --unix, --show-os.
327
328   Filter Options
329       --exclude-content=REGEX
330           Exclude files containing text that matches the given regular
331           expression.
332
333       --exclude-dir=DIR1[,DIR2 ...]
334           Exclude the given comma separated directories from being scanned.
335           For example:
336
337                   --exclude-dir=.cache,test
338
339           will skip all files that match "/.cache/" or "/test/" as part of
340           their path. Directories named ".bzr", ".cvs", ".hg", ".git", and
341           ".svn" are always excluded.  This option only works with individual
342           directory names so including file path separators is not allowed.
343           Use --fullpath and --not-match-d=REGEX to supply a regex matching
344           multiple subdirectories.
345
346       --exclude-ext=EXT1[,EXT2 ...]
347           Do not count files having the given file name extensions.
348
349       --exclude-lang=L1[,L2[...]]
350           Exclude the given comma separated languages from being counted.
351
352       --exclude-list-file=FILE
353           Ignore files and/or directories whose names appear in FILE.  FILE
354           should have one file name per line.  Only exact matches are
355           ignored; relative path names will be resolved starting from the
356           directory where cloc is invoked.  See also --list-file, --config.
357
358       --fullpath
359           Modifies the behavior of --match-f or --not-match-f to include the
360           file's path in the regex, not just the file's basename.  (This does
361           not expand each file to include its absolute path, instead it uses
362           as much of the path as is passed in to cloc.)
363
364       --include-ext=<ext1[,ext2[...]]>
365           Count only languages having the given comma separated file
366           extensions.  Use --show-ext to see the recognized extensions.
367
368       --include-lang=L1[,L2 ...]
369           Count only the given comma separated languages L1, L2, L3, et
370           cetera.
371
372       --match-d=REGEX
373           Only count files in directories matching the Perl regex.  For
374           example
375
376                --match-d='/(src|include)/'
377
378           only counts files in directory paths containing "/src/" or
379           "/include/".
380
381       --not-match-d=REGEX
382           Count all files except in directories matching the Perl regex.
383           Only the trailing directory name is compared, for example, when
384           counting in "/usr/local/lib", only "lib" is compared to the regex.
385           Add --fullpath to compare parent directories to the regex.  Do not
386           include file path separators at the beginning or end of the regex.
387
388       --match-f=REGEX
389           Only count files whose basenames match the Perl regex. For example
390           this only counts files at start with Widget or widget:
391
392                --match-f='^[Ww]idget'
393
394           Add --fullpath to include parent directories in the regex instead
395           of just the basename.
396
397       --not-match-f=REGEX
398           Count all files except those whose basenames match the Perl regex.
399           Add --fullpath to include parent directories in the regex instead
400           of just the basename.
401
402       --skip-archive=REGEX
403           Ignore files that end with the given Perl regular expression.  For
404           example, if given
405
406                   --skip-archive='(zip|tar(\.(gz|Z|bz2|xz|7z))?)'
407
408           the code will skip files that end with .zip, .tar, .tar.gz, .tar.Z,
409           .tar.bz2, .tar.xz, and .tar.7z.
410
411       --skip-win-hidden
412           On Windows, ignore hidden files.
413
414   Debug Options
415       --categorized=FILE
416           Save names of categorized files to FILE.
417
418       --counted=FILE
419           Save names of processed source files to FILE.
420
421       --diff-alignment=FILE
422           Write to FILE a list of files and file pairs showing which files
423           were added, removed, and/or compared during a run with --diff.
424           This switch forces the --diff mode on.
425
426       --explain=LANG
427           Print the filters used to remove comments for language LANG and
428           exit.  In some cases the filters refer to Perl subroutines rather
429           than regular expressions.  An examination of the source code may be
430           needed for further explanation.
431
432       --help
433           Print cloc's internal usage information and exit.
434
435       --found=FILE
436           Save names of every file found to FILE.
437
438       --ignored=FILE
439           Save names of ignored files and the reason they were ignored to
440           FILE.
441
442       --print-filter-stages
443           Print to STDOUT processed source code before and after each filter
444           is applied.
445
446       --show-ext[=EXT]
447           Print information about all known (or just the given) file
448           extensions and exit.
449
450       --show-lang[=LANG]
451           Print information about all known (or just the given) languages and
452           exit.
453
454       --show-os
455           Print the value of the operating system mode and exit.  See also
456           --unix, --windows.
457
458       -v[=N]
459           Turn on verbose with optional numeric value.
460
461       --verbose[=N]
462           Long form of -v.
463
464       --version
465           Print the version of this program and exit.
466
467       --write-lang-def=FILE
468           Writes to FILE the language processing filters then exits. Useful
469           as a first step to creating custom language definitions.  Note:
470           languages which map to the same file extension will be excluded.
471           See also --force-lang-def, --read-lang-def.
472
473       --write-lang-def-incl-dup=FILE
474           Same as --write-lang-def, but includes duplicated extensions.  This
475           generates a problematic language definition file because cloc will
476           refuse to use it until duplicates are removed.
477
478   Output Options
479       --3 Print third-generation language output.  (This option can cause
480           report summation to fail if some reports were produced with this
481           option while others were produced without it.)
482
483       --by-percent X
484           Instead of comment and blank line counts, show these values as
485           percentages based on the value of X in the denominator, where X is
486           one of
487               c   meaning lines of code
488               cm  meaning lines of code + comments
489               cb  meaning lines of code + blanks
490               cmb meaning lines of code + comments + blanks
491
492           For example, if using method 'c' and your code has twice as many
493           lines of comments as lines of code, the value in the comment column
494           will be 200%.  The code column remains a line count.
495
496       --csv
497           Write the results as comma separated values.
498
499       --csv-delimiter=C
500           Use the character C as the delimiter for comma separated files
501           instead of ,.  This switch forces --csv to be on.
502
503       --file-encoding=E
504           Write output files using the E encoding instead of the default
505           ASCII (E = 'UTF-7').  Examples: 'UTF-16', 'euc-kr', 'iso-8859-16'.
506           Known encodings can be printed with
507             perl -MEncode -e 'print join("\n", Encode->encodings(":all")),
508           "\n"'
509
510       --hide-rate
511           Do not show line and file processing rates in the output header.
512           This makes output deterministic.
513
514       --json
515           Write the results in JavaScript Object Notation (JSON).
516
517       --md
518           Write the results as Markdown-formatted text.
519
520       --out=FILE
521           Synonym for --report-file=FILE.
522
523       --progress-rate=N
524           Show progress update after every N files are processed (default
525           N=100). Set N to 0 to suppress progress output; useful when
526           redirecting output to STDOUT.
527
528       --quiet
529           Suppress all information messages except for the final report.
530
531       --report-file=FILE
532           Write the results to FILE instead of standard output.
533
534       --summary-cutoff=X:N
535           Aggregate to 'Other' results having X lines below N where X is one
536           of
537               c   meaning lines of code
538               f   meaning files
539               m   meaning lines of comments
540               cm  meaning lines of code + comments Appending a percent sign
541           to N changes the calculation from straight count to percentage.
542           Ignored with --diff or --by-file.
543
544       --sql=FILE
545           Write results as SQL CREATE and INSERT statements which can be read
546           by a database program such as SQLite. If FILE is -, output is sent
547           to STDOUT.
548
549       --sql-append
550           Append SQL insert statements to the file specified by --sql and do
551           not generate table creation option.
552
553       --sql-project=NAME
554           Use name as the project identifier for the current run. Only valid
555           with the --sql option.
556
557       --sql-style=STYLE
558           Write SQL statements in the given style instead of the default
559           SQLite format.  Styles include Oracle and Named_Columns.
560
561       --sum-one
562           For plain text reports, show the SUM: output line even if only one
563           input file is processed.
564
565       --xml
566           Write the results in XML.
567
568       --xsl[=FILE]
569           Reference FILE as an XSL stylesheet within the XML output. If FILE
570           is not given, writes a default stylesheet, cloc.xsl. This switch
571           forces --xml to be on.
572
573       --yaml
574           Write the results in YAML.
575

EXAMPLES

577       Count the lines of code in the Perl 5.10.0 compressed tar file on a
578       UNIX-like operating system:
579
580         cloc perl-5.10.0.tar.gz
581
582       Count the changes in files, code, and comments between Python releases
583       2.6.6 and 2.7:
584
585         cloc --diff Python-2.6.6.tar.bz  Python-2.7.tar.bz2
586
587       To see how cloc aligns files for comparison between two code bases, use
588       the --diff-alignment=FILE option.  Here the alignment information is
589       written to "align.txt":
590
591         cloc --diff-aligment=align.txt gcc-4.4.0.tar.bz2  gcc-4.5.0.tar.bz2
592
593       Count file, code, and comment changes between two git commits:
594
595         cloc --git --diff b409850824 HEAD
596
597       Print the recognized languages:
598
599         cloc --show-lang
600
601       Remove comments from "foo.c" and save the result in "foo.c.nc" ("nc" is
602       an arbitrary extension; used here to denote "no comments"):
603
604         cloc --strip-comments=nc foo.c
605
606       Additional examples can be found at <https://github.com/AlDanial/cloc>.
607

ENVIRONMENT

609       None.
610

FILES

612       None.
613

SEE ALSO

615       sloccount(1)
616

AUTHORS

618       The cloc program was written by Al Danial <al.danial@gmail.com> and is
619       Copyright (C) 2006-2019 <al.danial@gmail.com>.
620
621       The manual page was originally written by Jari Aalto
622       <jari.aalto@cante.net>.
623
624       Both the code and documentation is released under the GNU GPL version 2
625       or (at your option) any later version. For more information about
626       license, visit <http://www.gnu.org/copyleft/gpl.html>.
627
628
629
630cloc                              2023-07-19                           cloc(1)
Impressum