​
Why Command

The arc why command helps you understand the decision trail behind a specific line of code. It traverses the knowledge graph to find commits, PRs, issues, and other context that led to the current state of the code.

​
Usage

arc why file <file_path> <line_number> [options]

​
Subcommands

​
file

Show the decision trail for a specific line in a file. 
arc why file path/to/file.py 42

​
Options

OptionDescription
--max-depth <depth>Maximum depth to traverse in the knowledge graph (default: 3)
--include-issuesInclude related issues in the results
--include-prsInclude related pull requests in the results
--include-docsInclude related documentation in the results
--format <format>Output format: text, json, or markdown (default: text)
--output <file>Write output to a file instead of stdout
--debugEnable debug logging

​
Examples

​
Basic Usage

arc why file src/main.py 42
This will show the decision trail for line 42 in src/main.py.

​
With Maximum Depth

arc why file src/main.py 42 --max-depth 5
This will traverse the knowledge graph up to a depth of 5 to find related information.

​
Including Issues and PRs

arc why file src/main.py 42 --include-issues --include-prs
This will include related issues and pull requests in the results.

​
JSON Output

arc why file src/main.py 42 --format json
This will output the results in JSON format.

​
Output Format

The default output format is a text-based tree showing the decision trail: 
Decision Trail for src/main.py:42
├── Commit: abc123 (2023-01-15)
│   ├── Author: Jane Doe
│   ├── Message: Fix authentication bug
│   └── PR: #123 - Authentication improvements
│       ├── Issue: #100 - Users unable to log in
│       └── Discussion: #5 - Authentication design
└── Commit: def456 (2023-01-10)
    ├── Author: John Smith
    ├── Message: Initial implementation
    └── PR: #50 - User authentication feature

​
Comparison with trace

While the trace command focuses on the historical changes to a file or line, the why command focuses on understanding the decision-making process that led to the current state of the code.
Featurewhytrace
FocusDecision trailHistorical changes
Graph traversalBi-directionalLinear history
Default depth31
IncludesCommits, PRs, issues, docsCommits, file changes

​
Troubleshooting

​
No Results Found

If no results are found, try:
  1. Increasing the maximum depth with --max-depth
  2. Checking if the file and line number are correct
  3. Running arc build to ensure the knowledge graph is up to date

​
Performance Issues

For large repositories, the why command may take some time to execute. To improve performance:
  1. Use a smaller maximum depth
  2. Run an incremental build first: arc build --incremental
  3. Limit the scope of included data with specific options

​
See Also