How to use the command cloc (with examples)
The command cloc is a tool used for counting lines of source code and comments. It can be helpful for assessing the size and complexity of a project, identifying redundant code, and tracking progress during development. In this article, we will explore different use cases of the cloc command with examples.
Use case 1: Count all the lines of code in a directory
Code:
cloc path/to/directory
Motivation: This use case allows us to count all the lines of code in a specific directory. It can be useful when you want to get an overall understanding of the codebase and assess its size and complexity.
Explanation:
path/to/directory represents the path to the directory you want to analyze. Replace it with the actual directory path.
Example output:
22 text files.
22 unique files.
4 files ignored.
github.com/AlDanial/cloc v 1.88 T=3.18 s (5.9 files/s, 35.9 lines/s)
-------------------------------------------------------------------------------
Language files blank comment code
-------------------------------------------------------------------------------
Python 15 176 236 1120
JavaScript 1 5 6 89
YAML 1 1 0 18
Markdown 1 0 0 5
-------------------------------------------------------------------------------
SUM: 18 182 242 1232
-------------------------------------------------------------------------------
In the example output, we can see that the directory contains 22 text files, with 18 of them being used for counting lines of code. It provides a breakdown of the lines of code, comments, blanks, and other statistics for each programming language.
Use case 2: Count all the lines of code in a directory, displaying a progress bar
Code:
cloc --progress=1 path/to/directory
Motivation: When counting lines of code in a large directory, it can be helpful to see the progress of the counting process. The progress bar provides visual feedback, making it easier to estimate the remaining time.
Explanation:
--progress=1 enables the display of a progress bar during the counting process. The number represents the frequency of progress updates. Higher values will result in more frequent updates.
Example output:
86%|█████████████████████████████▌ | 224/260 [00:05<00:00, 42.6 files/s]
In this example, we can see a progress bar indicating that 86% of the counting process has been completed. It gives a visual representation of the progress, allowing us to track the process.
Use case 3: Compare 2 directory structures and count the differences
Code:
cloc --diff path/to/directory/one path/to/directory/two
Motivation: When working on different versions of a project or comparing different directory structures, it can be useful to identify the differences in lines of code. This use case helps to analyze the changes and understand the impact.
Explanation:
--diff enables the comparison between two directory structures. path/to/directory/one and path/to/directory/two represent the paths to the two directories you want to compare. Replace them with the actual directory paths.
Example output:
22 text files.
22 unique files.
4 files ignored.
github.com/AlDanial/cloc v 1.88 T=3.18 s (5.9 files/s, 35.9 lines/s)
-------------------------------------------------------------------------------
Language files blank comment code
-------------------------------------------------------------------------------
Python (added) 1 50 0 250
-------------------------------------------------------------------------------
SUM: 1 50 0 250
-------------------------------------------------------------------------------
In the example output, we can see the differences between path/to/directory/one and path/to/directory/two in terms of lines of code. In this case, one Python file with 50 lines of code has been added.
Use case 4: Ignore files ignored by VCS
Code:
cloc --vcs git path/to/directory
Motivation:
Sometimes, version control systems (VCS) ignore certain files, such as those specified in .gitignore. By ignoring these files during the counting process, we can obtain a more accurate analysis of the codebase.
Explanation:
--vcs git instructs cloc to ignore files that are ignored by the Git VCS. path/to/directory represents the directory you want to analyze. Replace it with the actual directory path.
Example output:
22 text files.
22 unique files.
3 files ignored.
github.com/AlDanial/cloc v 1.88 T=3.18 s (5.9 files/s, 35.9 lines/s)
-------------------------------------------------------------------------------
Language files blank comment code
-------------------------------------------------------------------------------
Python 15 176 236 1120
JavaScript 1 5 6 89
YAML 1 1 0 18
Markdown 1 0 0 5
-------------------------------------------------------------------------------
SUM: 18 182 242 1232
-------------------------------------------------------------------------------
In the example output, we can observe that three files were ignored by the Git VCS. As a result, the analysis excludes those files, providing a more accurate representation of the codebase.
Use case 5: Count all the lines of code in a directory, displaying results for each file
Code:
cloc --by-file path/to/directory
Motivation: In large projects with multiple files, it can be useful to see the line count for each individual file. This helps to identify specific files that contribute significantly to the overall line count.
Explanation:
--by-file instructs cloc to display the line count results for each file. path/to/directory represents the directory you want to analyze. Replace it with the actual directory path.
Example output:
22 text files.
22 unique files.
4 files ignored.
github.com/AlDanial/cloc v 1.88 T=3.18 s (5.9 files/s, 35.9 lines/s)
-------------------------------------------------------------------------------
Language files blank comment code
-------------------------------------------------------------------------------
Python 15 176 236 1120
JavaScript 1 5 6 89
YAML 1 1 0 18
Markdown 1 0 0 5
-------------------------------------------------------------------------------
SUM: 18 182 242 1232
-------------------------------------------------------------------------------
/path/to/directory/file1.py
34 text files.
34 unique files.
5 files ignored.
github.com/AlDanial/cloc v 1.88 T=3.18 s (5.9 files/s, 35.9 lines/s)
-------------------------------------------------------------------------------
Language files blank comment code
-------------------------------------------------------------------------------
Python 1 45 67 252
-------------------------------------------------------------------------------
SUM: 1 45 67 252
-------------------------------------------------------------------------------
<...Output for other files...>
In the example output, we can see the line count results for each file in the specified directory. Each file is displayed individually, showing the breakdown of lines of code, comments, and blanks. This allows us to analyze the distribution of lines of code across different files.
Conclusion:
The cloc command provides a variety of options for counting lines of source code and comments. By understanding and utilizing these different use cases, developers can gain insights into the size, complexity, and changes within a codebase. Whether it’s analyzing a specific directory, tracking progress, comparing directory structures, or filtering out VCS ignored files, cloc is a powerful tool for code analysis.
