https://github.com/chmouel/consult-vc-modified-files
List git modified files in a project with vc
https://github.com/chmouel/consult-vc-modified-files
consult emacs emacs-lisp emacs-mode git
Last synced: 4 months ago
JSON representation
List git modified files in a project with vc
- Host: GitHub
- URL: https://github.com/chmouel/consult-vc-modified-files
- Owner: chmouel
- License: gpl-3.0
- Created: 2023-10-19T05:06:55.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-07-24T22:21:29.000Z (4 months ago)
- Last Synced: 2025-07-25T04:31:13.059Z (4 months ago)
- Topics: consult, emacs, emacs-lisp, emacs-mode, git
- Language: Emacs Lisp
- Homepage:
- Size: 88.9 KB
- Stars: 15
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://stable.melpa.org/#/consult-vc-modified-files)
# ๐ consult-vc-modified-files
`consult-vc-modified-files` provides a easy way to list Git-tracked files that have been modified, newly added, or are part of the HEAD commit in a project.
It integrates with Emacs' built-in [vc](https://www.gnu.org/software/emacs/manual/html_node/emacs/Version-Control.html) and
[diff-mode](https://github.com/emacs-mirror/emacs/blob/master/lisp/vc/diff-mode.el) libraries,
as well as the [consult](https://github.com/minad/consult) package for navigation.
## โจ Features
- ๐ View **locally modified** files in the current Git project
- ๐ฆ List files from the HEAD commit
- ๐ List newly added (untracked) files separately
- ๐ Show files **staged for commit** in the Git staging area
- ๏ฟฝ๏ธ Select and explore files from **any past commit** with diff previews
- ๏ฟฝ๐ ๏ธ Customize sources for specific use cases
- ๐งญ Navigate the open files with `consult`
- ๐๏ธ Preview the diff or the commit for the current selection
- ๐ Smart preview window management (no more duplicate preview windows!)
- ๐ Show the commit message of the modified files in HEAD
- ๐งต Narrow to the right type of files with the `consult-narrow-key` (`>` by
default):
- `h` for modified in HEAD
- `a` added (untracked) files
- `l` modified locally
- `c` staged for commit.
> [!CAUTION]
> This only works with Git repositories and no other version control systems.
## ๐ธ Screenshot
### Preview with git show the HEAD files and git diff the modified files
### Browse modified files of a commit with `consult-vc-log-select-files`
## ๐ฅ Installation
### Using `use-package` and [MELPA](https://melpa.org/)
```elisp
(use-package consult-vc-modified-files
:bind
;; choose any other key bindings you prefer
(("C-x v /" . consult-vc-modified-files)
("C-x v ." . consult-vc-log-select-files)))
```
## ๐ Usage
### Browsing Modified Files
Call the interactive function `consult-vc-modified-files`, or use a key binding
like `C-x v /` (if configured with the configuration above).
When invoked, the command show a prompt for selecting files based on customizable sources:
- ๐ **Modified locally**: Lists locally modified or untracked files
- ๐ **Added files**: Lists new untracked files
- ๐ **Staged for commit**: Lists files added to the Git staging area
- ๐ฆ **Modified in HEAD**: Lists files modified in the HEAD commit
### Browsing Files from a Specific Commit
Call the interactive function `consult-vc-log-select-files` to:
1. Select a commit from the repository history
2. Choose a file that was modified in that commit
3. See a live diff preview of the changes made to that file in the commit
This is useful for reviewing changes from past commits without having to use a separate git tool.
You can customize the available sources using the
`consult-vc-modified-files-sources` variable.
## ๐ฎ Preview Features
- ๐ **Live diff preview**: See the changes in each file as you navigate through options
- ๐ง **Commit diff preview**: View exact changes made to files in any historical commit
- ๐ **Syntax highlighting**: Previews use diff-mode
## โ๏ธ Customization
### Configure Sources
You can customize which file categories appear in the selection when using
`consult-vc-modified-files` by setting the `consult-vc-modified-files-sources`
variable. This allows you to control exactly which types of files are presented
in the interface.
For example, if you want to show all modified files *except* those modified in
branch heads:
```elisp
(setq consult-vc-modified-files-sources
'(consult-vc-modified-files-source-modified-files
consult-vc-modified-files-source-added-files
consult-vc-modified-files-source-staged-files))
```
This configuration includes:
- Modified files (tracked files with changes)
- Added files (new untracked files)
- Staged files (changes ready for commit)
But it excludes files modified in branch heads.
### Display Git Commit Messages when showing the HEAD files
You can control whether to show commit message descriptions for files modified
in HEAD with the `consult-vc-modified-files-show-description` customization
option:
```elisp
(setq consult-vc-modified-files-show-description t) ;; Show descriptions (default is nil)
```
When enabled, this option displays the commit message next to each file modified
in the HEAD commit, providing more context about the changes.
- When `t`: Shows commit message descriptions for HEAD files
- When `nil`: Shows only the filenames without descriptions
### Customize Faces
Adjust the appearance of listed files by customizing:
- ๐จ `consult-vc-modified-files-face`: For locally modified files
- ๐ญ `consult-vc-modified-head-files-face`: For files modified in HEAD
- ๐ฉ `consult-vc-modified-files-added-face`: For new (untracked) files
- ๐ `consult-vc-modified-files-staged-face`: For files staged for commit
## ๐ฅ Authors
### Chmouel Boudjnah
- ๐ **Fediverse**: [@chmouel@chmouel.com](https://fosstodon.org/@chmouel) (preferred)
- ๐ฆ **Twitter**: [@chmouel](https://twitter.com/chmouel)
- ๐ **Blog**: [https://blog.chmouel.com](https://blog.chmouel.com)
## ๐ License
This project is licensed under the [GPL-3.0](./LICENSE).