CodeCharta Shell
The CodeCharta Shell (ccsh) is a convenient way to access the various tools. They in turn are divided into importers, filters and exporters.
- Importers take a source like Sonar and return a
.cc.json
- Filters take a
.cc.json
and return a.cc.json
- Exporters take a
.cc.json
and return the target format
If you want to combine multiple metrics into one .cc.json
you should get comfortable with the merge mapper. Some importers support direct pipe-through, which means you don’t have to use the merge mapper. If these importers are missing a metric, please take a look at Custom Metrics and Importer.
For further documentation considering the tools used in CodeCharta, please read the analysing-tools section.
Parser Suggestions
When launching CodeCharta Shell without any arguments and options, CodeCharta automatically tries to suggest useful parsers to the user. To do this, a resource has to be entered which can be a path to a file or folder or an url. CodeCharta then automatically checks all parsers which support this feature and offers the user to select from a list of all parsers which have been identified as applicable.
After choosing the parsers, a dry run to configure each parser is started using the Interactive Shell. When all parsers are configured, the user can either manually run the parsers by executing the command output by the Interactive Shell or run them together automatically. If the latter option is selected, all configured parsers are run in parallel.
If every parser is run successfully, the shell offers the user to merge the result files.
To do that, each parsers result cc.json
has to be moved into the same folder.
Currently, the following parsers are considered when checking for recommendations:
- GitLogParser
- SVNLogParser
- SonarImporter
- MetricGardenerImporter
- SourceCodeParser
- RawTextParser
Interactive Shell
The interactive shell aims to aid users when executing parsers by collecting all needed options and arguments for the corresponding parser.
You can launch the interactive shell by calling ccsh -i
or ccsh --interactive
.
There you are asked which parser you want to run and receive questions helping you configure that parser.
Alternatively, you can directly run the interactive dialog for a parser by calling it without arguments, e.g. ccsh sonarimport
.
In the end, the full command to launch the parser in the configured way is output for future use.
Filters
Edge Filter
Generates visualisation data from a cc.json file with edges data.
For every node its edge-attributes get aggregated and inserted as node-attribute.
After using this command the file can also be visualized inside the visualization, because the edgefilter
creates nodes,
if they did not exist before.
Usage
ccsh edgefilter [-h] [-o=<outputFile>]
[--path-separator=<pathSeparator>] FILE
Parameters
FILE files to filter
-h, --help displays this help and exits
-o, --output-file=<outputFile>
output File (or empty for stdout)
--path-separator=<pathSeparator>
path separator (default = '/')
Example
ccsh edgefilter edges.cc.json -o visual_edges.cc.json
Merge Filter
Reads the specified files and merges visualisation data.
The first file with visualisation data is used as reference for the merging strategy and a base for the output. The visualisation data in the additional json files, given they have the same API version, are fitted into this reference structure according to a specific strategy. Currently, there are two main strategies:
- recursive (default): leave structure of additional files. This will also merge optional edges.
- leaf (beta): fit leaf nodes into reference structure according to their name (and tail of their path),
either adding missing leaves (
--add-missing
) or ignoring them (default)
Both strategies will merge the unique list entries for attributeTypes
and blacklist
.
Usage
ccsh merge [-ah] [--ignore-case] [--leaf] [-nc] [--recursive]
[-o=<outputFile>] FILE or FOLDER...
Parameters
FILE or FOLDER... files to merge
-a, --add-missing enable adding missing nodes to reference
-h, --help displays this help and exits
--ignore-case ignores case when checking node names
--leaf leaf merging strategy
-nc, --not-compressed
save uncompressed output File
-o, --output-file=<outputFile>
output File (or empty for stdout)
--recursive recursive merging strategy (default)
Examples
ccsh merge file1.cc.json ../foo/file2.cc.json -o=test.cc.json
ccsh merge file1.cc.json ../foo/file2.cc.json -o=test.cc.json --leaf --add-missing
ccsh merge file1.cc.json ../foo/ -o=test.cc.json
(Merges all project files in foo with the reference file)
Structure Modifier
The Structure Modifier is used to modify the structure of .cc.json files. It enables to:
- remove nodes from a project. The resulting project will not include these nodes and their children.
- declare a node as root. This means that the chosen node will become the root node of the resulting sub-project.
- move nodes within the project. All children of the source node will be transferred to the destination node.
- print the hierarchy of the project.
The edges and blacklist entries associated with moved/removed nodes will be altered as well, while all attribute types will be copied.
Usage
ccsh modify [-h] [-f=<moveFrom>] [-o=<outputFile>]
[-p=<printLevels>] [-s=<setRoot>] [-t=<moveTo>]
[-r=<remove>...]... [FILE]
Parameters
[FILE] input project file
-f, --move-from=<moveFrom> move nodes in project folder...
-h, --help displays this help and exits
-o, --output-file=<outputFile> output File (or empty for stdout)
-p, --print-levels=<printLevels> show first x layers of project hierarchy
-r, --remove=<remove>... node(s) to be removed
-s, --set-root=<setRoot> path within project to be extracted
-t, --move-to=<moveTo> ... move nodes to destination folder
Examples
ccsh modify foo.cc.json -p=2
ccsh modify foo.cc.json --remove=/root/foo --remove=/root/bar/
ccsh modify foo.cc.json --move-from=/root/foo --move-to=/root/bar -output-file=project.cc.json
ccsh modify foo.cc.json --set-root=/root/foo/
Piped input
Instead of providing a cc.json file as input, a project can also be piped to the filter:
cat demo.cc.json | ccsh modify -p=2
Exporters
CSV Export
Generates CSV file with header from visualization data
Conventions for csv output:
- Every node with attributes contributes one line
- Column named path contains the hierarchical data of the node, separated via /
- Column named name contains the name of the node
- Column named type contains the type of the node
- Columns named Dir0, Dir1, … contain the split hierarchical data of the node for convenience
- The other columns contain the attributes of the nodes
Usage
ccsh csvexport [-h] [--depth-of-hierarchy=<maxHierarchy>]
[-o=<outputFile>] FILE...
Parameters
FILE... json files
--depth-of-hierarchy=<maxHierarchy>
depth of the hierarchy
-h, --help displays this help and exits
-o, --output-file=<outputFile>
output File (or empty for stdout)
Example
ccsh csvexport visual.cc.json