Tag Archives: git-diff

Using Emacs vc-diff with tools such as git-crypt or Rails credentials: Handling Binary Diff Issues

Reply

Tools like git-crypt or Rails credentials provide an encryption layer for managing sensitive files within Git repositories. However, when using Emacs vc-diff on repositories protected by these tools, the diff output is incorrect because vc-diff compares the encrypted binary files directly rather than comparing the decrypted files. This occurs even when the repository is unlocked and the decrypted content is available, resulting in a failure to display meaningful diffs.

The root cause

Internally, vc-diff uses Git commands to compute diffs. However, it does not invoke them with the --textconv flag by default. Without --textconv, Git does not apply content filters, including decryption filters specified by tools such as git-crypt or Rails credentials. Consequently, Emacs vc-diff displays diffs of the raw binary files rather than the decrypted content.

The solution

A workaround for enabling human-readable diffs of encrypted files in Emacs is to modify the vc-git-diff-switches variable to include the --textconv argument:

;; Emacs vc-diff fails to produce meaningful output on git-crypt enabled
;; repositories because it does not use Git's --textconv flag by default. This
;; flag enables Git to apply text conversion filters (e.g., for encrypted files)
;; when generating diffs. Without it, vc-diff compares raw encrypted blobs, even
;; when the working tree shows decrypted content.
(unless (member "--textconv" vc-git-diff-switches)
  (setq vc-git-diff-switches (cons "--textconv" vc-git-diff-switches)))Code language: Lisp (lisp)

Adding the --textconv flag to the vc-git-diff-switches variable enables Emacs vc-diff to apply the text conversion filters specified in .gitattributes. This resolves the issue by displaying the diff of the decrypted files instead of the encrypted binary files.

Further Reading

Enhancing Git Diff for Emacs Lisp: Better Git Diff of Elisp function or macro definitions

Reply

By default, the git diff algorithm compares changes in Elisp files line by line without understanding the structural semantics of Emacs Lisp files. This means that when modifications are made within functions, the diff output does not convey how those changes relate to higher-level code constructs such as functions or macros.

As a result, reviewers are presented with fragmented and often verbose diffs where the context of a change, such as which function it belongs to, is not always readily apparent. This lack of structural awareness can make it difficult to assess the purpose and impact of changes efficiently.

Git can be configured to recognize function or macro definitions explicitly, ensuring that diffs are presented at the function or macro level rather than as arbitrary line changes. Here are the steps:

Step 1 – The Git configuration for Emacs Lisp diffs

Add the following elisp Git driver to your ~/.gitconfig file:

[diff "elisp"]
xfuncname = ^\\([^[:space:]]*def[^[:space:]]+[[:space:]]+([^()[:space:]]+)
Code language: plaintext (plaintext)

The regular expression above matches lines that begin with typical Emacs Lisp definition forms, such as defun, defmacro, and other def* constructs. It detects the symbol being defined, allowing Git to handle changes at the function or definition level intelligently. This configuration can also be found in the autogen.sh file, which is part of the Emacs source code.

Step 2 – Associating the Git Diff Driver with *.el files

Once the custom diff driver is defined, it needs to be associated with Elisp files. This is accomplished by adding the following line to the ~/.gitattributes file:

*.el diff=elisp
Code language: plaintext (plaintext)

With this setup, Git will apply the elisp diff driver to all files with the .el extension, using the custom pattern to identify function boundaries.

Conclusion

This configuration generates diffs that focus on changes within the scope of individual function and macro definitions, rather than arbitrary lines. As a result, reviews of Emacs Lisp code become more precise and contextually relevant. Reviewers can easily identify which functions were modified, without being distracted by unrelated or excessive diffs.

Related links

Git: Suppressing Irrelevant Git Diff Output for Specific Files (e.g., binary files, encrypted files…)

Reply

Sometimes, it is useful to suppress certain files from git diff output, especially when the files are large, machine-generated, or not intended for human reading. Typical examples include encrypted files such as *.gpg and *.asc, as well as binary assets like images, audio files, and similar media. These files are usually represented as opaque binary data in diffs, providing no useful information and adding extraneous clutter to git diff output.

Git offers a solution for this through adding YOUR-FILE-PATTERN -diff -text to the .gitattributes file.

Solution: A .gitattributes file that is local to the repository

The .gitattributes file can be defined locally within each individual repository.

For example, to prevent git diff from displaying diffs for files with the .asc and .gpg extensions, include the following lines in the .gitattributes file at the root of your Git repository:

*.asc -diff -text
*.gpg -diff -textCode language: plaintext (plaintext)

Using -diff -text in .gitattributes is beneficial for binary or non-human-readable files because it ensures Git neither attempts to generate textual diffs (-diff) nor applies any text-related processing like end-of-line normalization (-text).

This combination prevents irrelevant or misleading changes from appearing in diffs, avoids potential corruption from automatic text conversions, and keeps version control output clean and focused on meaningful, human-readable changes.

Alternative solution: A global .gitattributes_global file

Rather than adding these rules to every repository individually, you can define them once in a global ~/.gitattributes_global file. This file applies to all Git repositories for your user account unless overridden by a repository-specific .gitattributes.

To set up a global .gitattributes_global file:

Configure Git to use it:

git config --global core.attributesfile ~/.gitattributes_globalCode language: plaintext (plaintext)

Add global rules to the ~/.gitattributes_global file. For example:

*.asc -diff -text -diff
*.gpg -diff -text -diffCode language: plaintext (plaintext)

This setup ensures consistent handling of non-human-readable files across all repositories without the need for redundant configuration.

Conclusion

Suppressing diffs for non-human-readable files with .gitattributes, whether configured locally or globally, reduces noise in version control workflows. This keeps Git diff output focused on meaningful textual modifications, prevents clutter from binary content, and safeguards against unwanted transformations.

Related links