Skip to content

Commit 415a4d9

Browse files
sumansaurabhsumansaurabh
authored
Sdg 786/blogs (#41)
* feat(docs): add comprehensive Penify CLI documentation and example workflows * feat(docs): add detailed documentation for Penify CLI's docgen command and Git hook integration * feat(docs): enhance README with detailed usage instructions and command options
1 parent b7cc134 commit 415a4d9

6 files changed

Lines changed: 1164 additions & 0 deletions

File tree

‎docs/commit-commands.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Penify CLI - Commit Commands
2+
3+
The `commit` command allows you to generate smart, AI-powered commit messages for your Git changes. This document explains all available options and combinations.
4+
5+
## Basic Usage
6+
7+
```bash
8+
penifycli commit
9+
```
10+
11+
By default, this command:
12+
- Analyzes your staged Git changes
13+
- Generates a concise commit title only
14+
- Uses local LLM if configured, or falls back to Penify API
15+
16+
## Command Options
17+
18+
### `-m, --message`
19+
20+
Provide context for the commit message generation:
21+
22+
```bash
23+
penifycli commit -m "Fix login flow"
24+
```
25+
26+
This hint helps the AI understand your intention and improves the quality of the generated message.
27+
28+
### `-e, --terminal`
29+
30+
Open an editor to review and edit the generated commit message before committing:
31+
32+
```bash
33+
penifycli commit -e
34+
```
35+
36+
This opens your default Git editor with the generated message for review.
37+
38+
### `-d, --description`
39+
40+
Generate a detailed commit message with both title and description:
41+
42+
```bash
43+
penifycli commit -d
44+
```
45+
46+
Without this flag, only the commit title is generated.
47+
48+
## Option Combinations
49+
50+
You can combine these options for different workflows:
51+
52+
### Generate Title Only with Context
53+
54+
```bash
55+
penifycli commit -m "Update login UI"
56+
```
57+
58+
### Generate Title and Description with Context
59+
60+
```bash
61+
penifycli commit -m "Update login UI" -d
62+
```
63+
64+
### Generate and Edit Full Commit Message
65+
66+
```bash
67+
penifycli commit -d -e
68+
```
69+
70+
### Generate, Edit, and Provide Context
71+
72+
```bash
73+
penifycli commit -m "Refactor authentication" -d -e
74+
```
75+
76+
## LLM and JIRA Integration
77+
78+
### Using Local LLM
79+
80+
If you've configured a local LLM using `penifycli config llm`, the commit command will automatically use it for message generation.
81+
82+
Benefits:
83+
- Privacy: your code changes don't leave your machine
84+
- Speed: no network latency
85+
- Works offline
86+
87+
### JIRA Enhancement
88+
89+
If you've configured JIRA integration using `penifycli config jira`, the commit command will:
90+
91+
1. Detect JIRA issue references in your changes
92+
2. Fetch issue details from your JIRA instance
93+
3. Include issue information in the commit message
94+
4. Format the commit message according to JIRA's smart commit format
95+
96+
Example output:
97+
```
98+
PROJ-123: Fix authentication bug in login flow
99+
100+
- Updated OAuth token validation
101+
- Fixed session timeout handling
102+
- Added unit tests for edge cases
103+
104+
[PROJ-123]
105+
```
106+
107+
## Configuration Requirements
108+
109+
For the `commit` command to work:
110+
111+
1. You must have configured either:
112+
- Local LLM via `penifycli config llm`, OR
113+
- Logged in via `penifycli login`
114+
115+
2. For JIRA enhancement (optional):
116+
- Configure JIRA via `penifycli config jira`
117+
118+
## Examples
119+
120+
### Basic Commit with Default Settings
121+
122+
```bash
123+
# Stage your changes
124+
git add .
125+
126+
# Generate commit message
127+
penifycli commit
128+
129+
# Commit with the generated message
130+
git commit -m "Generated message here"
131+
```
132+
133+
### Full Workflow with All Features
134+
135+
```bash
136+
# Stage your changes
137+
git add .
138+
139+
# Generate detailed commit message with JIRA integration,
140+
# provide context, and open editor for review
141+
penifycli commit -m "Fix login issue" -d -e
142+
143+
# The commit is automatically completed after you save and exit the editor
144+
```
145+
146+
## Troubleshooting
147+
148+
### Common Issues
149+
150+
1. **"No LLM model or API token provided"**
151+
- Run `penifycli config llm` to configure a local LLM, or
152+
- Run `penifycli login` to authenticate with Penify
153+
154+
2. **"Failed to connect to JIRA"**
155+
- Check your JIRA configuration with `cat ~/.penify`
156+
- Verify your network connection
157+
- Ensure your JIRA credentials are valid
158+
159+
3. **"Error initializing LLM client"**
160+
- Verify your LLM configuration settings
161+
- Ensure the LLM API is accessible

‎docs/config-commands.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# Penify CLI - Configuration Commands
2+
3+
The `config` command allows you to set up and manage configuration settings for Penify CLI. This document explains all available configuration options and how to use them.
4+
5+
## Configuration Overview
6+
7+
Penify CLI stores configuration in a JSON file at `~/.penify/config.json`. The configuration includes:
8+
9+
- LLM (Large Language Model) settings for local commit message generation
10+
- JIRA integration settings for enhanced commit messages
11+
- API tokens and other credentials
12+
13+
## Basic Usage
14+
15+
```bash
16+
# Configure LLM settings
17+
penifycli config llm
18+
19+
# Configure JIRA integration
20+
penifycli config jira
21+
```
22+
23+
## LLM Configuration
24+
25+
### Web Interface
26+
27+
Running `penifycli config llm` opens a web interface in your browser where you can configure:
28+
29+
1. **Model**: The LLM model to use (e.g., `gpt-3.5-turbo`)
30+
2. **API Base URL**: The endpoint URL for your LLM API (e.g., `https://api.openai.com/v1`)
31+
3. **API Key**: Your authentication key for the LLM API
32+
33+
### Supported LLMs
34+
35+
Penify CLI supports various LLM providers:
36+
37+
#### OpenAI
38+
- Model: `gpt-3.5-turbo` or `gpt-4`
39+
- API Base: `https://api.openai.com/v1`
40+
- API Key: Your OpenAI API key
41+
42+
#### Anthropic
43+
- Model: `claude-instant-1` or `claude-2`
44+
- API Base: `https://api.anthropic.com/v1`
45+
- API Key: Your Anthropic API key
46+
47+
#### Ollama (Local)
48+
- Model: `llama2` or any model you have installed
49+
- API Base: `http://localhost:11434`
50+
- API Key: (leave blank)
51+
52+
#### Azure OpenAI
53+
- Model: Your deployed model name
54+
- API Base: Your Azure endpoint
55+
- API Key: Your Azure API key
56+
57+
### Configuration File Structure
58+
59+
After configuration, your `~/.penify/config.json` will contain:
60+
61+
```json
62+
{
63+
"llm": {
64+
"model": "gpt-3.5-turbo",
65+
"api_base": "https://api.openai.com/v1",
66+
"api_key": "sk-..."
67+
}
68+
}
69+
```
70+
71+
## JIRA Configuration
72+
73+
### Web Interface
74+
75+
Running `penifycli config jira` opens a web interface where you can configure:
76+
77+
1. **JIRA URL**: Your JIRA instance URL (e.g., `https://yourcompany.atlassian.net`)
78+
2. **Username**: Your JIRA username (typically your email)
79+
3. **API Token**: Your JIRA API token
80+
81+
### Creating a JIRA API Token
82+
83+
1. Log in to [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
84+
2. Click "Create API token"
85+
3. Give it a name (e.g., "Penify CLI")
86+
4. Copy the generated token and paste it into the configuration
87+
88+
### Configuration File Structure
89+
90+
After configuration, your `~/.penify/config.json` will contain:
91+
92+
```json
93+
{
94+
"jira": {
95+
"url": "https://yourcompany.atlassian.net",
96+
"username": "your.email@example.com",
97+
"api_token": "your-jira-api-token"
98+
}
99+
}
100+
```
101+
102+
## Configuration Locations
103+
104+
Penify CLI looks for configuration in multiple locations:
105+
106+
1. Project-specific: `.penify/config.json` in the Git repository root
107+
2. User-specific: `~/.penify/config.json` in your home directory
108+
109+
The project-specific configuration takes precedence if both exist.
110+
111+
## Environment Variables
112+
113+
You can override configuration settings using environment variables:
114+
115+
- `PENIFY_API_TOKEN`: Override the stored API token
116+
- `PENIFY_LLM_MODEL`: Override the configured LLM model
117+
- `PENIFY_LLM_API_BASE`: Override the configured LLM API base URL
118+
- `PENIFY_LLM_API_KEY`: Override the configured LLM API key
119+
- `PENIFY_JIRA_URL`: Override the configured JIRA URL
120+
- `PENIFY_JIRA_USER`: Override the configured JIRA username
121+
- `PENIFY_JIRA_TOKEN`: Override the configured JIRA API token
122+
123+
Example:
124+
```bash
125+
export PENIFY_LLM_MODEL="gpt-4"
126+
penifycli commit
127+
```
128+
129+
## Command-Line Configuration
130+
131+
For advanced users or scripting, you can directly edit the configuration file:
132+
133+
```bash
134+
# View current configuration
135+
cat ~/.penify/config.json
136+
137+
# Edit configuration with your preferred editor
138+
nano ~/.penify/config.json
139+
```
140+
141+
## Sharing Configuration
142+
143+
You can share configuration between machines by copying the `.penify/config.json` file. However, be cautious with API keys and credentials.
144+
145+
For team settings, consider:
146+
1. Using a project-specific `.penify/config.json` with shared settings
147+
2. Excluding API keys from shared configuration
148+
3. Using environment variables for sensitive credentials
149+
150+
## Troubleshooting
151+
152+
### Common Issues
153+
154+
1. **"Error reading configuration file"**
155+
- Check if the file exists: `ls -la ~/.penify`
156+
- Ensure it contains valid JSON: `cat ~/.penify/config.json`
157+
158+
2. **"Failed to connect to LLM API"**
159+
- Verify API base URL and API key
160+
- Check network connectivity to the API endpoint
161+
- Ensure your account has access to the specified model
162+
163+
3. **"Failed to connect to JIRA"**
164+
- Check JIRA URL format (should include `https://`)
165+
- Verify username and API token
166+
- Ensure your JIRA account has API access permissions

0 commit comments

Comments
 (0)