​

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

​

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.

​

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

• Trace Command - For tracing the historical changes to a file or line
• Relate Command - For finding related nodes in the knowledge graph
• Tracing History Examples - For more examples of using the why command