1cloc(1) User Commands cloc(1)
2
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 --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 --extract-with='gzip -dc >FILE< | tar xf -
34 or, if you have GNU tar:
36 --extract-with='tar zxf >FILE<'
38 and on Windows, use, for example:
40 --extract-with="\"c:\Program Files\WinZip\WinZip32.exe\" -e -o >FILE<
42 --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 --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 --unicode
66 Check binary files to see if they contain Unicode expanded ASCII
67 text. This causes performance to drop noticeably.
68 Processing Options
70 --autoconf
71 Count .in files (as processed by GNU autoconf) of recognized
72 languages. See also --no-autogen.
73 --by-file
75 Report results for every source file encountered.
76 --by-file-by-lang
78 Report results for every source file encountered in addition to
79 reporting by language.
80 --config FILE
82 First perform direct code counts of source file(s)
83 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 --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 --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 --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 --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 --follow-links
119 [Unix only] Follow symbolic links to directories (sym links to
120 files are always followed).
121 --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 --force-lang="Fortran 90",f
129 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 --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 --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 --ignore-whitespace
157 Ignore horizontal white space when comparing files with --diff.
158 See also --ignore-case.
159 --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 --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 --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 --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 --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 --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 --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 --script-lang=Perl,perl5.8.8
203 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 --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 --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 --stdin-name=FILE
219 Count lines streamed via STDIN as if they came from a file named
220 FILE.
221 --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 --original-dir
230 Write the stripped files the same directory as the original files.
231 Only effective in combination with --strip-comments.
232 --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 --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 --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 --unix
256 Over-ride the operating system detection logic and run in UNIX
257 mode. See also --windows, --show-os.
258 --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 --windows
269 Over-ride the operating system detection logic and run in Microsoft
270 Windows mode. See also --unix, --show-os.
271 Filter Options
273 --exclude-dir=DIR1[,DIR2 ...]
274 Exclude the given comma separated directories from being scanned.
275 For example:
276 --exclude-dir=.cache,test
278 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 --exclude-ext=EXT1[,EXT2 ...]
287 Do not count files having the given file name extensions.
288 --exclude-lang=L1[,L2[...]]
290 Exclude the given comma separated languages from being counted.
291 --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 --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 --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 --include-lang=L1[,L2 ...]
309 Count only the given comma separated languages L1, L2, L3, et
310 cetera.
311 --match-d=REGEX
313 Only count files in directories matching the Perl regex. For
314 example
315 --match-d='/(src|include)/'
317 only counts files in directory paths containing "/src/" or
319 "/include/".
320 --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 --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 --match-f='^[Ww]idget'
333 Add --fullpath to include parent directories in the regex instead
335 of just the basename.
336 --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 --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 --skip-win-hidden
350 On Windows, ignore hidden files.
351 Debug Options
353 --categorized=FILE
354 Save names of categorized files to FILE.
355 --counted=FILE
357 Save names of processed source files to FILE.
358 --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 --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 --help
371 Print cloc's internal usage information and exit.
372 --found=FILE
374 Save names of every file found to FILE.
375 --ignored=FILE
377 Save names of ignored files and the reason they were ignored to
378 FILE.
379 --print-filter-stages
381 Print to STDOUT processed source code before and after each filter
382 is applied.
383 --show-ext[=EXT]
385 Print information about all known (or just the given) file
386 extensions and exit.
387 --show-lang[=LANG]
389 Print information about all known (or just the given) languages and
390 exit.
391 --show-os
393 Print the value of the operating system mode and exit. See also
394 --unix, --windows.
395 -v[=N]
397 Turn on verbose with optional numeric value.
398 --verbose[=N]
400 Long form of -v.
401 --version
403 Print the version of this program and exit.
404 --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 --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 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 --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 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 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 --csv
435 Write the results as comma separated values.
436 --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 --hide-rate
442 Do not show line and file processing rates in the output header.
443 This makes output deterministic.
444 --json
446 Write the results in JavaScript Object Notation (JSON).
447 --md
449 Write the results as Markdown-formatted text.
450 --out=FILE
452 Synonym for --report-file=FILE.
453 --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 --quiet
460 Suppress all information messages except for the final report.
461 --report-file=FILE
463 Write the results to FILE instead of standard output.
464 --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 --sql-append
471 Append SQL insert statements to the file specified by --sql and do
472 not generate table creation option.
473 --sql-project=NAME
475 Use name as the project identifier for the current run. Only valid
476 with the --sql option.
477 --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 --sum-one
483 For plain text reports, show the SUM: output line even if only one
484 input file is processed.
485 --xml
487 Write the results in XML.
488 --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 --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 cloc perl-5.10.0.tar.gz
502 Count the changes in files, code, and comments between Python releases
504 2.6.6 and 2.7:
505 cloc --diff Python-2.6.6.tar.bz Python-2.7.tar.bz2
507 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 cloc --diff-aligment=align.txt gcc-4.4.0.tar.bz2 gcc-4.5.0.tar.bz2
513 Count file, code, and comment changes between two git commits:
515 cloc --git --diff b409850824 HEAD
517 Print the recognized languages:
519 cloc --show-lang
521 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 cloc --strip-comments=nc foo.c
526 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 The manual page was originally written by Jari Aalto
543 <jari.aalto@cante.net>.
544 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>.
548cloc 2020-07-27 cloc(1)