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