Statamic Changelog Laravel Package

Getting Started

eminos/statamic-changelog is a Statamic 6 addon that surfaces your project’s git log inside the Control Panel. It is aimed at teams who want an in-CP activity feed without maintaining a manual changelog.

Minimum setup:

composer require eminos/statamic-changelog

Before relying on it, confirm the runtime environment:

• PHP 8.3+
• Statamic 6.0+
• git binary available to the PHP process
• The project’s .git directory is present and readable on the server

No further setup is required for the default experience: the changelog icon appears in the CP top nav automatically. Look first at the package config if you need to tailor what appears — publish it if the package provides a publish tag, or inspect vendor/eminos/statamic-changelog/config directly. The config is where you should expect to control commit limit, path/author/message filters, merge exclusion, and the Statamic Git addon visibility toggle.

First practical use case: open the changelog in the CP after a deploy and confirm the latest commits are visible to the team. Then use the per-user “unseen” badge as a lightweight “what changed since I last looked” indicator for editors and developers.

Implementation Patterns

Default team activity feed. Install and leave the config mostly untouched. The top-nav badge gives each CP user a personal count of new commits since their last visit, which works well as a low-effort awareness tool for content and development changes.

Filter to editorial paths. For content teams, restrict the log to paths that matter to them, e.g. content/, resources/views/, or specific blueprint directories. This turns the changelog from a developer firehose into a content-change feed. Keep a broader view for developers if needed by using separate environments or accepting the path filter as a team-wide compromise.

Filter by author or message convention. If your team uses ticket prefixes or conventional commit messages, use the message-pattern regex filter to show only relevant work — e.g. commits matching a project key. Author filtering is useful for reviewing a specific teammate’s recent changes, but avoid hard-coding a single author if the changelog is meant for the whole team.

Hide Statamic Git addon noise. If you use Statamic’s built-in Git addon, enable the integration toggle. It filters out the default Spock user and Content saved messages, which otherwise dominate the log during editorial activity. This is the single most useful toggle for content-heavy sites.

Exclude merge commits. Enable merge exclusion for a cleaner linear view. Keep it disabled if your workflow relies on merge commit messages to summarize feature work.

Per-user tracking as a workflow signal. The timestamp-based “last seen” state survives rebases and history rewrites, which is deliberate. Use it as a personal “since I last checked” marker rather than an audit trail. It is not a replacement for release notes or a formal changelog.

Pair with deployment checks. After deploy, verify the changelog reflects the expected release commit. This is a quick smoke test that the deployed code and the visible history match.

Gotchas and Tips

.git must exist in the deployed application. The package reads the repository directly. Builds that export only application files, or container images that exclude .git, will break the changelog. Ensure deployments include the repository metadata, or accept that the feature is unavailable in those environments.

Shallow clones truncate history. CI checkouts with depth: 1 leave little or no history for the changelog. Use a full clone or set fetch-depth: 0 in your CI checkout step if the changelog is expected to show meaningful history.

Git must be callable by the web process. The git binary may be available in your shell but not in the PHP-FPM/container PATH. Reproduce issues by running git log as the same user and environment as the application. Also check .git ownership: newer Git versions can refuse to read repositories owned by a different user unless safe.directory is configured.

Timestamp-based “last seen” has trade-offs. Because tracking uses timestamps rather than commit hashes, rebases and history rewrites do not reset a user’s state. That is usually desirable, but backdated commits or rewritten history can produce unexpected unseen counts. New users may see a large initial count depending on how the initial state is handled — verify behaviour for your team.

Regex filters need care. Message-pattern filtering is powerful but can be expensive or surprising. Test patterns against real git log output, anchor them where appropriate, and avoid overly broad patterns that accidentally include unrelated commits. Be cautious with user-supplied or complex regex patterns.

The Statamic Git integration toggle is narrow. It targets the addon’s default Spock user and Content saved messages. If your Statamic Git addon uses custom commit messages or a different author configuration, those commits may still appear.

Large repositories can be slow. Use the configurable commit limit to keep the CP responsive. If the repository has years of history, avoid fetching the entire log by default.

Config caching applies. After changing the package config, run php artisan config:clear (or your normal config cache refresh) in environments where configuration is cached.

Dark mode styling is provided, but custom overrides can break it. If you publish and modify views, use Statamic’s CP CSS variables rather than hard-coded colours so light/dark themes remain consistent.

Debugging approach. Reproduce the exact git log command the package would run as the application user, from the project root. If the CP shows nothing, check .git presence, permissions, shallow clone depth, and whether filters are excluding everything. Check Laravel logs for process execution errors.

Extension points. The config is the primary integration surface for filters, limits, merge exclusion, and Statamic Git awareness. If deeper customisation is needed, inspect the package service provider and whether views/config are publishable; publishing views is the usual path for presentation changes without forking.