How to Turn Git Commits Into a Changelog: The Complete Guide

Every developer knows the pain of manually writing release notes. You've just shipped a new version of your software, and now you need to document all the changes. But what if you could automatically generate a professional changelog directly from your git commit history?

The good news is that you can—and it's easier than you think. In this guide, we'll walk through the complete process of turning your git commits into meaningful changelogs that your users will actually want to read.

Why Automate Your Changelog?

Before we dive into the how, let's talk about the why:

Save Time: No more manually reviewing commits before each release
Reduce Errors: Eliminate the risk of missing important changes
Maintain Consistency: Every changelog follows the same format and style
Improve User Experience: Users get accurate, timely information about updates
Better Release Management: Clear visibility into what's changing in each version

The Foundation: Conventional Commits

The secret to automated changelog generation is using conventional commit messages. This standardized format makes your commits machine-readable while remaining human-friendly.

What Are Conventional Commits?

Conventional commits follow this structure:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Essential Commit Types for Changelogs

Not all commits should appear in your changelog. Here are the types that matter:

feat: New features for users
fix: Bug fixes that resolve user-facing issues
perf: Performance improvements
refactor: Code changes that improve maintainability
docs: Documentation updates (usually not in changelogs)
test: Test additions/changes (usually not in changelogs)
chore: Maintenance tasks (usually not in changelogs)
style: Code style changes (usually not in changelogs)

Examples of Changelog-Worthy Commits

feat: add dark mode support to user interface
feat(auth): implement OAuth 2.0 authentication
fix: resolve memory leak in image processing
fix(api): handle timeout errors gracefully
perf: optimize database queries for user search
refactor: simplify user validation logic

Setting Up Your Git Workflow

1. Install Commitizen (Optional but Recommended)

Commitizen helps enforce conventional commit format:

npm install -g commitizen
npm install -g cz-conventional-changelog

Then initialize it in your project:

commitizen init cz-conventional-changelog --save-dev --save-exact

2. Configure Your Git Hooks

Set up pre-commit hooks to validate commit message format:

npm install --save-dev @commitlint/cli @commitlint/config-conventional

Create .commitlintrc.js:

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'chore']
    ],
    'subject-case': [2, 'always', 'lower-case'],
    'subject-max-length': [2, 'always', 72]
  }
}

3. Set Up Husky for Git Hooks

npm install --save-dev husky
npx husky install
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

Manual Changelog Generation

If you prefer to start manually, here's how to generate a changelog from your git history:

Using Git Log Commands

# Get all commits since the last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline

# Get commits with more detail
git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:"- %s (%h)" --grep="^feat\|^fix\|^perf\|^refactor"

# Get commits by type
git log --grep="^feat" --pretty=format:"- %s (%h)"
git log --grep="^fix" --pretty=format:"- %s (%h)"

Creating a Basic Changelog Template

# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

### Added
- List new features here

### Changed
- List changes in existing functionality here

### Deprecated
- List soon-to-be removed features here

### Removed
- List removed features here

### Fixed
- List any bug fixes here

### Security
- List security fixes here

## [1.0.0] - 2025-01-28

### Added
- Initial release

Automated Changelog Generation

While manual generation works, automation is where the real magic happens. Here are some popular tools:

1. Conventional Changelog CLI

npm install --save-dev conventional-changelog-cli

Generate a changelog:

npx conventional-changelog -p angular -i CHANGELOG.md -s

2. GitHub Actions Integration

Create .github/workflows/changelog.yml:

name: Generate Changelog

on:
  push:
    tags:
      - 'v*'

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Generate Changelog
        run: |
          npx conventional-changelog-cli -p angular -i CHANGELOG.md -s -r 0

      - name: Commit Changelog
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add CHANGELOG.md
          git commit -m "docs: update changelog for ${{ github.ref_name }}"
          git push

3. ShipLog: The Professional Solution

For teams that want a more sophisticated approach, ShipLog provides enterprise-grade changelog automation:

Automatic Webhook Integration: Connects directly to your GitHub repository
Smart Change Detection: Automatically categorizes commits and pull requests
Professional Templates: Beautiful, branded changelog pages
Team Collaboration: Multiple team members can review and edit before publishing
Custom Domains: Host changelogs on your own domain
Analytics: Track how users engage with your changelogs

Best Practices for Commit-Based Changelogs

1. Be Specific in Your Commits

# ❌ Too vague
fix: fix bug

# ✅ Specific and actionable
fix: resolve login timeout on slow connections

2. Use Scopes for Better Organization

feat(auth): add two-factor authentication
fix(api): handle rate limiting errors
perf(database): optimize user search queries

3. Write Clear, User-Focused Descriptions

# ❌ Technical implementation details
feat: implement JWT token validation middleware

# ✅ User-focused description
feat: add secure authentication with JWT tokens

4. Include Breaking Changes

feat!: remove deprecated API endpoints

BREAKING CHANGE: The following endpoints have been removed:
- /api/v1/users/legacy
- /api/v1/auth/basic

Advanced Techniques

1. Linking Issues and Pull Requests

feat: add user profile management

Closes #123
Related to #456

2. Grouping Related Changes

feat(auth): implement OAuth 2.0 authentication

- Add OAuth 2.0 provider integration
- Implement refresh token rotation
- Add social login options (Google, GitHub)

3. Semantic Versioning Integration

Automatically determine version bumps based on commit types:

feat: Minor version bump
fix: Patch version bump
BREAKING CHANGE: Major version bump

Common Pitfalls to Avoid

1. Inconsistent Commit Messages

# ❌ Mixed formats
feat: add new feature
Added another feature
FIX: bug fix

# ✅ Consistent conventional format
feat: add new feature
feat: add another feature
fix: resolve bug

2. Including Irrelevant Commits

# ❌ These shouldn't be in changelogs
chore: update dependencies
style: fix formatting
test: add unit tests

# ✅ These should be in changelogs
feat: add user dashboard
fix: resolve login issue
perf: optimize search algorithm

3. Vague Change Descriptions

# ❌ Unclear what changed
fix: fix stuff
feat: add things

# ✅ Clear and specific
fix: resolve memory leak in image upload
feat: add dark mode toggle to settings

Setting Up Your First Automated Changelog

Here's a step-by-step guide to get you started:

Step 1: Install Dependencies

npm install --save-dev conventional-changelog-cli
npm install --save-dev @commitlint/cli @commitlint/config-conventional
npm install --save-dev husky

Step 2: Configure Commit Linting

Create .commitlintrc.js:

module.exports = {
  extends: ['@commitlint/config-conventional']
}

Step 3: Set Up Git Hooks

npx husky install
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

Step 4: Create Initial Changelog

npx conventional-changelog -p angular -i CHANGELOG.md -s -r 0

Step 5: Make Your First Conventional Commit

git add .
git commit -m "feat: add automated changelog generation"

When to Use Different Approaches

Manual Generation

Use for: Small projects, infrequent releases, learning purposes
Pros: Full control, no dependencies
Cons: Time-consuming, error-prone, inconsistent

Open Source Tools

Use for: Medium projects, teams comfortable with CLI tools
Pros: Free, customizable, community support
Cons: Requires setup, limited features, maintenance overhead

Professional Services (Like ShipLog)

Use for: Teams, businesses, frequent releases, professional appearance
Pros: Zero setup, beautiful UI, team collaboration, analytics
Cons: Monthly cost, less customization

Conclusion

Automating your changelog generation from git commits is one of the best investments you can make in your development workflow. It saves time, reduces errors, and ensures your users always have accurate information about your software updates.

The key is starting with conventional commits and gradually building up your automation. Whether you choose open-source tools or a professional service like ShipLog, the important thing is to get started.

Your future self (and your users) will thank you for it.

Next Steps

Start Today: Begin using conventional commit messages in your next commit
Set Up Linting: Install commit message validation to enforce the format
Choose Your Tool: Decide between manual generation, open-source tools, or professional services
Iterate: Start simple and add complexity as your needs grow

Remember, the best changelog system is the one you'll actually use. Start small, be consistent, and watch your release process become smoother with every update.

Ready to automate your changelog generation? Try ShipLog for free and see how easy it can be to turn your git commits into professional changelogs that your users love.

How to Turn Git Commits Into a Changelog: The Complete Guide

Why Automate Your Changelog?

The Foundation: Conventional Commits

What Are Conventional Commits?

Essential Commit Types for Changelogs

Examples of Changelog-Worthy Commits

Setting Up Your Git Workflow

1. Install Commitizen (Optional but Recommended)

2. Configure Your Git Hooks

3. Set Up Husky for Git Hooks

Manual Changelog Generation

Using Git Log Commands

Creating a Basic Changelog Template

Automated Changelog Generation

1. Conventional Changelog CLI

2. GitHub Actions Integration

3. ShipLog: The Professional Solution

Best Practices for Commit-Based Changelogs

1. Be Specific in Your Commits

2. Use Scopes for Better Organization

3. Write Clear, User-Focused Descriptions

4. Include Breaking Changes

Advanced Techniques

1. Linking Issues and Pull Requests

2. Grouping Related Changes

3. Semantic Versioning Integration

Common Pitfalls to Avoid

1. Inconsistent Commit Messages

2. Including Irrelevant Commits

3. Vague Change Descriptions

Setting Up Your First Automated Changelog

Step 1: Install Dependencies

Step 2: Configure Commit Linting

Step 3: Set Up Git Hooks

Step 4: Create Initial Changelog

Step 5: Make Your First Conventional Commit

When to Use Different Approaches

Manual Generation

Open Source Tools

Professional Services (Like ShipLog)

Conclusion

Next Steps

Enjoyed this article?