Quickstart

This guide will walk you through running DeepLint for the first time and understanding its output.

This is part of the Getting Started series:

1. Installation

2. Configuration

3. First Run (current page)

4. Git Integration

Prerequisites

Before running DeepLint, ensure you have:

1. Installed DeepLint

2. Configured DeepLint (optional, default configuration works for most cases)

3. A Git repository with some changes (either staged or unstaged)

Running DeepLint

After installing and configuring DeepLint, you can run it with a simple command:

deeplint

When run without arguments, DeepLint will:

1. Look for staged changes in your Git repository

2. Build context for analysis

3. Display information about the context (number of files, tokens, etc.)

If you don't have any staged changes, DeepLint will exit early with a message indicating that no changes were found. You can use the --unstaged flag to analyze unstaged changes instead.

LLM-Powered Analysis (AI Linting)

DeepLint can analyze your code using powerful Large Language Models (LLMs) like OpenAI's GPT-4o. This enables advanced linting, code review, and suggestions powered by AI.

Requirements

• OpenAI API Key: You need an OpenAI API key to use LLM-powered analysis.

  • Get one at platform.openai.com
  • Set it as an environment variable:

    export OPENAI_API_KEY=sk-...

  • Or add it to your config file under llm.apiKey.

• Model: By default, DeepLint uses gpt-4o. You can change this with the --model flag or in your config.

Quickstart: LLM Analysis

To run DeepLint with LLM-powered analysis, use the check command:

deeplint check

This will:

1. Build context from your code changes

2. Send the context to the LLM for analysis

3. Display lint results, explanations, and suggestions

Example: Analyze with a Custom Model

deeplint check --model=gpt-4

Example: Add Custom Instructions

deeplint check --instructions="Focus on security issues."

Example: Output as JSON

deeplint check --json

Example: Analyze Unstaged Changes

deeplint check --unstaged

LLM Options

You can control the LLM analysis with these options:

• --provider (default: openai)

• --model (default: gpt-4o)

• --api-key (your OpenAI API key)

• --instructions (extra prompt instructions)

• --json (output as JSON)

• --unstaged (include unstaged changes)

See the Check Command Guide for full details.

LLM analysis requires an internet connection and may use your OpenAI API quota. Results depend on the model and your code context.

Command Line Options

DeepLint supports several command line options to customize its behavior:

# Run with debug output
deeplint --debug

# Include unstaged changes
deeplint --unstaged

# Save context to a file for inspection
deeplint --dump context.json

# Enable verbose output
deeplint --verbose

# Combine multiple options
deeplint --debug --unstaged

For a complete list of options, run:

deeplint help

Understanding the Output

When you run DeepLint, you'll see output similar to this:

INFO: Running DeepLint on staged changes...
INFO: Building context for analysis...
INFO: Context built with 3 changed files and 5 related files
INFO: Context building statistics:
INFO: - Total files: 8
INFO: - Changed files: 3
INFO: - Related files: 5
INFO: - Total tokens: 4567
INFO: - Build time: 234ms
INFO: Context built successfully!
INFO: Ready for LLM analysis.
INFO: DeepLint analysis completed.

Let's break down what this means:

• Running DeepLint on staged changes: DeepLint is analyzing the changes you've staged with git add.

• Building context for analysis: DeepLint is gathering information about your codebase.

• Context built with X changed files and Y related files: DeepLint has identified the files you've changed and other files that are related to those changes.

• Context building statistics: Information about the context that was built, including the number of files, tokens, and build time.

• Ready for LLM analysis: The context is ready for analysis by the LLM.

Inspecting the Context

If you want to see what information DeepLint is gathering for analysis, you can use the --dump option:

deeplint --dump context.json

This will save the context to a file, which you can examine to understand what information DeepLint is gathering. The context includes:

• Repository information (name, root, structure)

• Changes (files, diffs, summary)

• Related files (dependencies, content, structure)

• Metadata (token counts, generation time)

Troubleshooting

No Staged Changes

If you run DeepLint without any staged changes, you'll see an error message:

ERROR: No staged changes found. Stage changes with 'git add' or use --unstaged to analyze unstaged changes.

To fix this, either:

1. Stage some changes with git add, or

2. Use the --unstaged flag to analyze unstaged changes:

deeplint --unstaged

Not a Git Repository

If you run DeepLint outside of a Git repository, you'll see an error message:

ERROR: Not a Git repository. Initialize a Git repository with 'git init' or navigate to a Git repository.

To fix this, either:

1. Navigate to a Git repository, or

2. Initialize a Git repository in your current directory:

git init

Token Limit Exceeded

If your codebase is large, you might see a warning about token limits:

WARN: Token limit exceeded. Some files may be truncated or excluded.

This means that DeepLint had to truncate or exclude some files to stay within the token limit. To address this, you can:

1. Reduce the number of files being analyzed by making smaller, more focused changes.

2. Adjust the token limits in your configuration file:

contextBuilder: {
  maxTokens: 8000,  // Increase this value
  tokensPerFile: 1000,  // Adjust this value
}

Debug Mode

If you're having issues with DeepLint, you can run it in debug mode to get more information:

deeplint --debug

This will show detailed information about the context building process, including:

INFO: Building context for LLM analysis...
INFO: Found staged changes. Proceeding with context building...
INFO: Analyzing staged changes in 3 files
INFO: Scanning repository...
INFO: Found 127 files (89 source files, 38 test files)
INFO: Building dependency graph...
INFO: Analyzing code structure...
INFO: Assembling context...
INFO: Context built in 1243ms
INFO: Context size: 5678 tokens (2345 for changes, 3333 for related files)

Verbose Mode

For more detailed output without the technical details of debug mode, you can use verbose mode:

deeplint --verbose

This will show additional information about what DeepLint is doing, such as:

🔊 Context building configuration:
🔊 - Repository root: /path/to/your/project
🔊 - Include unstaged changes: false
🔊 - Max tokens: 8000
🔊 - Include dependencies: true
🔊 - Include structure: true
🔊 Starting context building process...
🔊 Context building process completed.

For more information about verbose mode, see the Verbose Mode guide.

Understanding the Context Building Process

When you run DeepLint, it goes through several steps to build context for analysis:

1. Git Integration: DeepLint checks for staged or unstaged changes in your Git repository

2. Repository Scanning: DeepLint scans your repository to understand its structure

3. Dependency Analysis: DeepLint analyzes dependencies between files

4. Code Structure Analysis: DeepLint extracts information about the structure of your code

5. Context Assembly: DeepLint assembles all this information into a structured context

6. Token Management: DeepLint manages the context size to fit within token limits

For more detailed information about the context building process, see the Context Building documentation.

Next Steps

Now that you've run DeepLint for the first time, you can:

1. Learn more about Git integration to automate DeepLint in your workflow
2. Explore the configuration options to customize DeepLint for your project
3. Learn about the command line options to get the most out of DeepLint

Developer Note: The context building process is highly optimized to provide the most relevant information while staying within token limits. It's designed to work with a wide range of codebases and can be customized to fit your specific needs.

---

Previous: Configuration | Next: Git Integration →