Add a built-in userdiff driver for the Swift programming language so that diff hunk headers and word diffs work out of the box for ".swift" files.

The funcname pattern is built for Swift's own declaration grammar: an optional run of attributes ("@objc", "@available(iOS 13, *)", ...), followed by an optional run of lowercase modifiers ("public", "static", "final", ...), followed by a declaration keyword (func, class, struct, enum, protocol, extension, actor, init, deinit, subscript). The keyword is followed by a boundary that allows whitespace, "(" (init/subscript), "?" or "!" (failable init), or "<" (generics), while still acting as a word boundary so e.g. "initialize(" does not match.

The word regex recognizes Swift identifiers, hexadecimal, octal, binary, integer and floating-point literals, and the language's operators.

Signed-off-by: Shlok Kulshreshtha <diy2903@gmail.com>
---
This addresses the "add a userdiff driver for a language" microproject.
Swift is not covered by a built-in driver yet, and I did not find an
in-flight patch adding one on the list; please let me know if one exists.

Motivation: without a Swift driver, ".swift" files use the generic
funcname heuristic, so "git diff" hunk headers name the enclosing type
instead of the changed function.

The pattern is built directly from Swift's declaration grammar rather than adapted from another language's driver, so it covers a few things that a straight port would miss:

 - attributes, with or without arguments, whether on their own line
   ("@objc" above a "func") or inline with the declaration
   ("@objc func foo()", "@available(iOS 13, *) public func bar()");
 - modifiers ("public", "static", "override", "mutating", ...) in any
   combination, before or after attributes;
 - failable initializers, "init?" and "init!";
 - generics, "init<T>" and "subscript<T>";
 - the keyword boundary still acts as a word boundary, so e.g.
   "initialize(" is not mistaken for "init".

I verified all of the above against a built binary, including generic functions with "where" clauses, multi-line signatures, and operator functions such as "static func ==". I did not find a real case this pattern misses; the ones I intentionally left out are one-line declarations ("typealias", "associatedtype") and rarer forms ("operator", "precedencegroup", "macro"), which would not make useful section headers anyway.

The word regex covers Swift identifiers; hexadecimal, octal, binary, integer and floating-point literals; and operators including "<<=" / ">>=", "??" and the range operators. All of t4018 passes, including the sorted builtin_drivers check and the new swift-* fixtures.

 Documentation/gitattributes.adoc  |  2 ++
 t/t4018/swift-actor               |  5 +++++
 t/t4018/swift-attribute-with-args |  7 +++++++
 t/t4018/swift-class               |  5 +++++
 t/t4018/swift-enum                |  5 +++++
 t/t4018/swift-extension           |  5 +++++
 t/t4018/swift-failable-init       |  7 +++++++
 t/t4018/swift-func                |  5 +++++
 t/t4018/swift-generic-subscript   |  7 +++++++
 t/t4018/swift-init                |  7 +++++++
 t/t4018/swift-inline-attribute    |  7 +++++++
 t/t4018/swift-modifiers           |  4 ++++
 t/t4018/swift-protocol            |  5 +++++
 t/t4018/swift-struct              |  5 +++++
 userdiff.c                        | 10 ++++++++++
 15 files changed, 86 insertions(+)
 create mode 100644 t/t4018/swift-actor
 create mode 100644 t/t4018/swift-attribute-with-args
 create mode 100644 t/t4018/swift-class
 create mode 100644 t/t4018/swift-enum
 create mode 100644 t/t4018/swift-extension
 create mode 100644 t/t4018/swift-failable-init
 create mode 100644 t/t4018/swift-func
 create mode 100644 t/t4018/swift-generic-subscript
 create mode 100644 t/t4018/swift-init
 create mode 100644 t/t4018/swift-inline-attribute
 create mode 100644 t/t4018/swift-modifiers
 create mode 100644 t/t4018/swift-protocol
 create mode 100644 t/t4018/swift-struct

Shlok Kulshreshtha <diy2903@gmail.com> writes:

I do not work with this language myself, so I have no idea how well the pattern proposed here matches real-world code. Will queue, but it needs reviews and validaion from active Swift users before it can advance to 'next' and eventually to a future Git release.

Thanks.

Am 17.07.26 um 16:02 schrieb Shlok Kulshreshtha:

I am mildly surprised that userdiff drivers can count as microproject. At a minimum, they are on the challenging side of the spectrum.

AFAIC, the regular expression does not match attributes on their own line. What relevance does this statement have?

So, this doesn't pick up the "struct View {" line, but the line below. Good test.

This test contains "RIGHT" twice. This is not good, because we do not know which one is picked.

It is strange to have "RIGHT" twice on the same line, but it does no harm. Still, there should be only one for consistency.

Again "RIGHT" twice in a harmful way.

All other test cases look good.

This looks good.

Notice, however, how the regular expression matcher has to backtrack on even simple lines such as

class foo {

On the first attempt, [a-z]+ matches "class", but then "foo" does not match. On the next attempt, the clause with [a-z]+ matches zero times and the next clause matches "class" and, in total, successfully.

It may be worth considering to enumerate all keywords and permit any run of them:

	(public|final|etc.|func|init|...|actor)[ \t(?!<]+)+

It does not matter that this would match any assemblement of keywords; they wouldn't occur in correct Swift code anyway. (Or would they?)

You could just throw all of them into a single pattern like this:

	0[xXoObB][0-9a-fA-F_]+

except when, for example,

	0b1_abc

can occur in correct Swift code (perhaps the token 0b1 followd by the token _abc).

Ok. Is ".5" a correct floating-point number? If so, it would not be caught by this regular expression? But it wouldn't be particularly harmful, either, to leave it as is. The ".5" would just be parsed as two tokens, "." and "5".

You do not have to account for single-character operators; they are automatic. Drop the "?" from the first "=?".

These are my comments on the technical side. Since I do not speak Swift, I cannot comment on how reasonable your choice which lines to pick out is.

-- Hannes

Johannes Sixt <j6t@kdbg.org> writes:

I am, too ;-) It is hard to get them right, even though thanks to your earlier work long time ago, writing a test that demonstrates what is expected of the patterns is fairly easy to write.

Am 18.07.26 um 20:11 schrieb Johannes Sixt:

[...]

Let me back-paddle on this one. As I said, the original RE is good. I am making up a problem here without providing evidence. Modern RE matchers may be clever enough that there is no problem. If it turns out there is a problem, we can improve later something that already works.

-- Hannes

Johannes Sixt <j6t@kdbg.org> writes:

You are right. The pattern only matches attributes that are inline with the declaration. An attribute on its own line is not matched, and does not need to be, because the declaration line below it matches on its own. I have reworded this.

[...]

Fixed in a coming v2: swift-init, swift-failable-init and swift-generic-subscript now contain "RIGHT" only once, on the declaration line.

Noted, and thanks for the follow-up on this one. I did check it anyway out of curiosity: with that shape, a line that is only modifiers and never reaches a real declaration keyword, such as

	public var counter = 0

would still match, because it merges modifiers and declaration keywords into one interchangeable run. The current pattern requires a real keyword at the end, so that line correctly gets no header. I will keep the current form for now, and can revisit if the backtracking turns out to matter in practice.

Right -- that is why I kept them as three separate patterns, so the digit ranges stay correct (binary [01], octal [0-7]); merging would mis-tokenize "0b1_abc".

No -- Swift requires a leading digit, so ".5" is a syntax error (one must write "0.5"). Tokenizing it as "." and "5" is therefore fine, and it does not occur in valid Swift.

Done in a coming v2, thanks; I had not realized PATTERNS appends "|[^[:space:]]". It is a nice simplification, and it only touches the word regex, not the funcname pattern.

Since neither of us speaks Swift, for your ease of judgement I have also put together some coverage numbers, which the coming v2 cover note will include:

 - Grammar: I went through every declaration form listed in the "Summary
   of the Grammar" in Swift's own language reference (func, init incl.
   failable/generic, deinit, subscript incl. generic, class, struct,
   enum, protocol, extension, actor, operator methods, stacked
   modifiers, attributes with and without arguments, "where" clauses,
   multi-line signatures -- 26 forms total) and wrote a case for each.
   All 26 get the correct header.

 - Real-world code: I ran the driver over the last 200 commits touching
   *.swift in seven different Swift projects -- Alamofire,
   apple/swift-argument-parser, vapor, Kingfisher, RxSwift, SnapKit, and
   pointfreeco/swift-composable-architecture -- and checked every hunk
   header by hand. Out of 20454 hunks, 15310 got a header, and 15296 of
   those (99.9%) named a real declaration. None of the empty-header
   hunks turned out to be a real miss (they were things like file
   comment blocks, imports, or Package.swift, which have nothing to
   attach a header to).

These numbers are unaffected by the changes in this reply: the funcname pattern is identical in v1 and v2 (only the word regex and the test files changed), and both measurements are of hunk headers, which come from the funcname pattern alone. So the coverage above still holds for v2.

Besides the fixes above, v2 will also carry the reworded attribute description and the changelog explaining what changed since v1, so the full picture is in one place when you look at it.

Thanks for the careful review. Shlok

Add a built-in userdiff driver for the Swift programming language so that diff hunk headers and word diffs work out of the box for ".swift" files.

The funcname pattern is built for Swift's own declaration grammar: an optional run of attributes ("@objc", "@available(iOS 13, *)", ...), followed by an optional run of lowercase modifiers ("public", "static", "final", ...), followed by a declaration keyword (func, class, struct, enum, protocol, extension, actor, init, deinit, subscript). The keyword is followed by a boundary that allows whitespace, "(" (init/subscript), "?" or "!" (failable init), or "<" (generics), while still acting as a word boundary so e.g. "initialize(" does not match.

The word regex recognizes Swift identifiers, hexadecimal, octal, binary, integer and floating-point literals, and the language's operators.

Signed-off-by: Shlok Kulshreshtha <diy2903@gmail.com>
---
v2, addressing Johannes Sixt's review of v1
(<2a3a73c5-5e90-44a3-bf6a-6e98ce5e5a59@kdbg.org>).  Changes since v1:

 - t4018/swift-{init,failable-init,generic-subscript}: "RIGHT" now
   appears only once, on the declaration line, so the expected header is
   unambiguous.
 - word regex: dropped the redundant "?" after the single-character
   operator class.  Single characters are already covered by the
   "|[^[:space:]]" fallback that the PATTERNS macro appends, so only the
   two-character forms need to be spelled out.

(A couple of Hannes's other suggestions I kept as-is; I have explained the reasoning in a reply to his review.)

Some coverage evidence beyond the t4018 fixtures:

 - Grammar: a test over every declaration form in Swift's grammar
   summary (26 forms -- func/class/struct/enum/protocol/extension/actor,
   init incl. "init?"/"init!"/generic, deinit, subscript incl. generic,
   operator methods, stacked modifiers, inline attributes with and
   without arguments, "where" clauses, multi-line signatures) -- all 26
   resolve to the correct declaration.

 - Corpus: run over the last 200 commits touching *.swift in seven
   stylistically different projects (Alamofire, apple/
   swift-argument-parser, vapor, Kingfisher, RxSwift, SnapKit,
   pointfreeco/swift-composable-architecture): of 20454 hunks, 15310
   produced a header and 15296 (99.9%) named a real declaration.  The
   empty-header hunks are changes with no enclosing declaration (file
   comment blocks, imports, Package.swift, top-level code); sampling
   found no change inside a declaration that failed to get a header.
   The handful of non-declaration headers are the selective-import form
   ("import class Foundation.Bundle"), which reads "import" as a
   modifier; rare and low-harm, and I can exclude it in a follow-up if
   preferred.

 Documentation/gitattributes.adoc  |  2 ++
 t/t4018/swift-actor               |  5 +++++
 t/t4018/swift-attribute-with-args |  7 +++++++
 t/t4018/swift-class               |  5 +++++
 t/t4018/swift-enum                |  5 +++++
 t/t4018/swift-extension           |  5 +++++
 t/t4018/swift-failable-init       |  7 +++++++
 t/t4018/swift-func                |  5 +++++
 t/t4018/swift-generic-subscript   |  7 +++++++
 t/t4018/swift-init                |  7 +++++++
 t/t4018/swift-inline-attribute    |  7 +++++++
 t/t4018/swift-modifiers           |  4 ++++
 t/t4018/swift-protocol            |  5 +++++
 t/t4018/swift-struct              |  5 +++++
 userdiff.c                        | 10 ++++++++++
 15 files changed, 86 insertions(+)
 create mode 100644 t/t4018/swift-actor
 create mode 100644 t/t4018/swift-attribute-with-args
 create mode 100644 t/t4018/swift-class
 create mode 100644 t/t4018/swift-enum
 create mode 100644 t/t4018/swift-extension
 create mode 100644 t/t4018/swift-failable-init
 create mode 100644 t/t4018/swift-func
 create mode 100644 t/t4018/swift-generic-subscript
 create mode 100644 t/t4018/swift-init
 create mode 100644 t/t4018/swift-inline-attribute
 create mode 100644 t/t4018/swift-modifiers
 create mode 100644 t/t4018/swift-protocol
 create mode 100644 t/t4018/swift-struct

Shlok Kulshreshtha <diy2903@gmail.com> writes:

Thanks for an update.

Let's wait for a few days to see if we hear more comments and otherwise mark the topic for 'next'.

Am 21.07.26 um 21:33 schrieb Junio C Hamano:

This round looks good to me.

Acked-by: Johannes Sixt <j6t@kdbg.org>

-- Hannes

On Tue, Jul 21, 2026 at 12:06 AM Shlok Kulshreshtha <diy2903@gmail.com> wrote:

I noticed other languages add a test_language_driver entry to t/t4034-diff-words.sh with corresponding pre/post/expect fixtures. Should we add something similar for Swift?

Am 27.07.26 um 07:03 schrieb Michael Montalbo:

We could that. But since the words are basically run-of-the-mill and nothing exotic (like we had for the scheme driver), I gladly forgo a test script at this time. In the past, these test scripts turned out to be non-trivial to get correct and it was a burden for both the author and the reviewers. It would certainly exceed the scope of a microproject.

-- Hannes

On Sun, Jul 26, 2026 at 11:44 PM Johannes Sixt <j6t@kdbg.org> wrote:

[snip]

Got it, thanks for the context.

FWIW, I tested the changes against a recent WWDC 2026 sample project[1] I was playing around with, and the new user driver appears to work well.

[1] https://developer.apple.com/documentation/FoundationModels/origami-crafting-a-dynamic-tutorial-for-apple-intelligence