Skip to contentSkip to conversation

userdiff: add support for Swift

PATCH Superseded Shlok Kulshreshtha 4 participants 12 messages Jul 17 – Jul 27 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 userdiff: add support for Swift

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.

---
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
Documentation/gitattributes.adoc +2 -0
index bd76167a45..9fea75f96f 100644
@@ -914,6 +914,8 @@ patterns are available:
 - `scheme` suitable for source code in most Lisp dialects,
   including Scheme, Emacs Lisp, Common Lisp, and Clojure.
 
+- `swift` suitable for source code in the Swift language.
+
 - `tex` suitable for source code for LaTeX documents.
 
 
t/t4018/swift-actor new file +5 -0
new file mode 100644
index 0000000000..e4852f40a7
@@ -0,0 +1,5 @@
+actor RIGHT {
+    let a = 1
+    // a comment
+    let b = ChangeMe
+}
t/t4018/swift-attribute-with-args new file +7 -0
new file mode 100644
index 0000000000..22b1ee32f1
@@ -0,0 +1,7 @@
+struct View {
+    @available(iOS 13, *) public func RIGHT() {
+        let a = 1
+        // a comment
+        print(ChangeMe)
+    }
+}
t/t4018/swift-class new file +5 -0
new file mode 100644
index 0000000000..c3a9336027
@@ -0,0 +1,5 @@
+class RIGHT {
+    let a = 1
+    // a comment
+    let b = ChangeMe
+}
t/t4018/swift-enum new file +5 -0
new file mode 100644
index 0000000000..0a84302993
@@ -0,0 +1,5 @@
+enum RIGHT {
+    case first
+    // a comment
+    case ChangeMe
+}
t/t4018/swift-extension new file +5 -0
new file mode 100644
index 0000000000..cbc18ab6ef
@@ -0,0 +1,5 @@
+extension RIGHT {
+    static let a = 1
+    // a comment
+    static let b = ChangeMe
+}
t/t4018/swift-failable-init new file +7 -0
new file mode 100644
index 0000000000..5e4091d97c
@@ -0,0 +1,7 @@
+class Bar {
+    init?(RIGHT: Int) {
+        let value = RIGHT
+        // a comment
+        print(ChangeMe)
+    }
+}
t/t4018/swift-func new file +5 -0
new file mode 100644
index 0000000000..1fecae0911
@@ -0,0 +1,5 @@
+func RIGHT(x: Int) -> Int {
+    let y = x
+    // a comment
+    return ChangeMe
+}
t/t4018/swift-generic-subscript new file +7 -0
new file mode 100644
index 0000000000..565f93cd6c
@@ -0,0 +1,7 @@
+struct Container {
+    subscript<RIGHT>(index: RIGHT) -> Int {
+        let a = 0
+        // a comment
+        return ChangeMe
+    }
+}
t/t4018/swift-init new file +7 -0
new file mode 100644
index 0000000000..f683e74794
@@ -0,0 +1,7 @@
+class Foo {
+    init(RIGHT: Int) {
+        let value = RIGHT
+        // a comment
+        print(ChangeMe)
+    }
+}
t/t4018/swift-inline-attribute new file +7 -0
new file mode 100644
index 0000000000..2374c4b603
@@ -0,0 +1,7 @@
+class Service {
+    @objc func RIGHT() {
+        let path = "/api"
+        // a comment
+        log(ChangeMe)
+    }
+}
t/t4018/swift-modifiers new file +4 -0
new file mode 100644
index 0000000000..9d80685a78
@@ -0,0 +1,4 @@
+public static func RIGHT() -> Int {
+    // a comment
+    return ChangeMe
+}
t/t4018/swift-protocol new file +5 -0
new file mode 100644
index 0000000000..07c39ec2a3
@@ -0,0 +1,5 @@
+protocol RIGHT {
+    var first: Int { get }
+    // a comment
+    var second: ChangeMe { get }
+}
t/t4018/swift-struct new file +5 -0
new file mode 100644
index 0000000000..e399ed7759
@@ -0,0 +1,5 @@
+struct RIGHT {
+    let a = 1
+    // a comment
+    let b = ChangeMe
+}
userdiff.c +10 -0
index b5412e6bc3..df37dd78a6 100644
@@ -362,6 +362,16 @@ PATTERNS("scheme",
 	 "\\|([^|\\\\]|\\\\.)*\\|"
 	 /* All other words should be delimited by spaces or parentheses. */
 	 "|([^][)(}{ \t])+"),
+PATTERNS("swift",
+	 "^[ \t]*((@[A-Za-z_][A-Za-z0-9_]*(\\([^()]*\\))?[ \t]+)*([a-z]+[ \t]+)*(func|init|deinit|subscript|class|struct|enum|protocol|extension|actor)[ \t(?!<].*)$",
+	 /* -- */
+	 "[a-zA-Z_][a-zA-Z0-9_]*"
+	 /* hexadecimal, octal, and binary literals */
+	 "|0[xX][0-9a-fA-F_]+|0[oO][0-7_]+|0[bB][01_]+"
+	 /* integers and floating-point numbers */
+	 "|[0-9][0-9_]*([.][0-9_]+)?([eE][-+]?[0-9]+)?"
+	 /* unary and binary operators */
+	 "|[-+*/%<>=!&|^~?]=?|&&|\\|\\||<<=?|>>=?|\\?\\?|\\.\\.[.<]|->"),
 PATTERNS("tex", "^(\\\\((sub)*section|chapter|part)\\*{0,1}\\{.*)$",
 	 "\\\\[a-zA-Z@]+|\\\\.|([a-zA-Z0-9]|[^\x01-\x7f])+"),
 { .name = "default", .binary = -1 },
Signature · 1 line
2.52.0
#1 lore raw
Quoted 2 lines · Shlok Kulshreshtha

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.

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.

#2 lore raw
In reply to Shlok Kulshreshtha

Am 17.07.26 um 16:02 schrieb Shlok Kulshreshtha:

Quoted 12 lines

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.

Quoted 6 lines

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

---
This addresses the "add a userdiff driver for a language" microproject.

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

Quoted 7 lines

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.

Quoted 7 lines

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()");

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

Quoted 80 lines

- 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
Documentation/gitattributes.adoc +2 -0
index bd76167a45..9fea75f96f 100644
@@ -914,6 +914,8 @@ patterns are available:
 - `scheme` suitable for source code in most Lisp dialects,
   including Scheme, Emacs Lisp, Common Lisp, and Clojure.
 
+- `swift` suitable for source code in the Swift language.
+
 - `tex` suitable for source code for LaTeX documents.
 
 
t/t4018/swift-actor new file +5 -0
new file mode 100644
index 0000000000..e4852f40a7
@@ -0,0 +1,5 @@
+actor RIGHT {
+    let a = 1
+    // a comment
+    let b = ChangeMe
+}
t/t4018/swift-attribute-with-args new file +0 -0
new file mode 100644
index 0000000000..22b1ee32f1

t/t4018/swift-attribute-with-args line 7

Quoted 7 lines
t/t4018/swift-attribute-with-args new file +7 -0
@@ -0,0 +1,7 @@
+struct View {
+    @available(iOS 13, *) public func RIGHT() {
+        let a = 1
+        // a comment
+        print(ChangeMe)
+    }
+}

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

t/t4018/swift-failable-init line 7

Quoted 13 lines
t/t4018/swift-failable-init new file +7 -0
new file mode 100644
index 0000000000..5e4091d97c
@@ -0,0 +1,7 @@
+class Bar {
+    init?(RIGHT: Int) {
+        let value = RIGHT
+        // a comment
+        print(ChangeMe)
+    }
+}

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

t/t4018/swift-generic-subscript line 7

Quoted 13 lines
t/t4018/swift-generic-subscript new file +7 -0
new file mode 100644
index 0000000000..565f93cd6c
@@ -0,0 +1,7 @@
+struct Container {
+    subscript<RIGHT>(index: RIGHT) -> Int {
+        let a = 0
+        // a comment
+        return ChangeMe
+    }
+}

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

t/t4018/swift-init line 7

Quoted 13 lines
t/t4018/swift-init new file +7 -0
new file mode 100644
index 0000000000..f683e74794
@@ -0,0 +1,7 @@
+class Foo {
+    init(RIGHT: Int) {
+        let value = RIGHT
+        // a comment
+        print(ChangeMe)
+    }
+}

Again "RIGHT" twice in a harmful way.

All other test cases look good.

userdiff.c PATTERNS("scheme", · line 366

Quoted 10 lines
userdiff.c +2 -0
index b5412e6bc3..df37dd78a6 100644
@@ -362,6 +362,16 @@ PATTERNS("scheme",
 	 "\\|([^|\\\\]|\\\\.)*\\|"
 	 /* All other words should be delimited by spaces or parentheses. */
 	 "|([^][)(}{ \t])+"),
+PATTERNS("swift",
+	 "^[ \t]*((@[A-Za-z_][A-Za-z0-9_]*(\\([^()]*\\))?[ \t]+)*([a-z]+[ \t]+)*(func|init|deinit|subscript|class|struct|enum|protocol|extension|actor)[ \t(?!<].*)$",

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?)

userdiff.c PATTERNS("scheme", · line 370

Quoted 4 lines
userdiff.c +4 -0
+	 /* -- */
+	 "[a-zA-Z_][a-zA-Z0-9_]*"
+	 /* hexadecimal, octal, and binary literals */
+	 "|0[xX][0-9a-fA-F_]+|0[oO][0-7_]+|0[bB][01_]+"

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).

userdiff.c PATTERNS("scheme", · line 372

Quoted 2 lines
userdiff.c +2 -0
+	 /* integers and floating-point numbers */
+	 "|[0-9][0-9_]*([.][0-9_]+)?([eE][-+]?[0-9]+)?"

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".

userdiff.c PATTERNS("scheme", · line 374

Quoted 2 lines
userdiff.c +2 -0
+	 /* unary and binary operators */
+	 "|[-+*/%<>=!&|^~?]=?|&&|\\|\\||<<=?|>>=?|\\?\\?|\\.\\.[.<]|->"),

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

#3 lore raw
Quoted 16 lines · Johannes Sixt

Am 17.07.26 um 16:02 schrieb Shlok Kulshreshtha:

Quoted 15 lines

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.

Quoted 6 lines
Quoted 3 lines

---
This addresses the "add a userdiff driver for a language" microproject.

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

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.

#4 lore raw
In reply to Johannes Sixt

Am 18.07.26 um 20:11 schrieb Johannes Sixt:

Quoted 8 lines

Am 17.07.26 um 16:02 schrieb Shlok Kulshreshtha:

userdiff.c PATTERNS("scheme", · line 366

Quoted 2 lines
userdiff.c +2 -0
+PATTERNS("swift",
+	 "^[ \t]*((@[A-Za-z_][A-Za-z0-9_]*(\\([^()]*\\))?[ \t]+)*([a-z]+[ \t]+)*(func|init|deinit|subscript|class|struct|enum|protocol|extension|actor)[ \t(?!<].*)$",

This looks good.

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

[...]

Quoted 2 lines

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

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

#5 lore raw
In reply to Johannes Sixt
Quoted 4 lines · Johannes Sixt
Quoted 2 lines

- attributes, with or without arguments, whether on their own line ("@objc" above a "func") or inline with the declaration

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

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.

Quoted 2 lines

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

[...]

Quoted 1 line

Again "RIGHT" twice in a harmful way.

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

Quoted 3 lines

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

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

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.

Quoted 3 lines

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

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".

Quoted 1 line

Is ".5" a correct floating-point number?

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.

Quoted 2 lines

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

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

#6 lore raw

PATCH v2 1/1 userdiff: add support for Swift

In reply to Shlok Kulshreshtha

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.

---
v2, addressing Johannes Sixt's review of v1 (<[email protected]>). 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
Documentation/gitattributes.adoc +2 -0
index bd76167a45..9fea75f96f 100644
@@ -914,6 +914,8 @@ patterns are available:
 - `scheme` suitable for source code in most Lisp dialects,
   including Scheme, Emacs Lisp, Common Lisp, and Clojure.
 
+- `swift` suitable for source code in the Swift language.
+
 - `tex` suitable for source code for LaTeX documents.
 
 
t/t4018/swift-actor new file +5 -0
new file mode 100644
index 0000000000..e4852f40a7
@@ -0,0 +1,5 @@
+actor RIGHT {
+    let a = 1
+    // a comment
+    let b = ChangeMe
+}
t/t4018/swift-attribute-with-args new file +7 -0
new file mode 100644
index 0000000000..22b1ee32f1
@@ -0,0 +1,7 @@
+struct View {
+    @available(iOS 13, *) public func RIGHT() {
+        let a = 1
+        // a comment
+        print(ChangeMe)
+    }
+}
t/t4018/swift-class new file +5 -0
new file mode 100644
index 0000000000..c3a9336027
@@ -0,0 +1,5 @@
+class RIGHT {
+    let a = 1
+    // a comment
+    let b = ChangeMe
+}
t/t4018/swift-enum new file +5 -0
new file mode 100644
index 0000000000..0a84302993
@@ -0,0 +1,5 @@
+enum RIGHT {
+    case first
+    // a comment
+    case ChangeMe
+}
t/t4018/swift-extension new file +5 -0
new file mode 100644
index 0000000000..cbc18ab6ef
@@ -0,0 +1,5 @@
+extension RIGHT {
+    static let a = 1
+    // a comment
+    static let b = ChangeMe
+}
t/t4018/swift-failable-init new file +7 -0
new file mode 100644
index 0000000000..4bbd6217c9
@@ -0,0 +1,7 @@
+class Bar {
+    init?(RIGHT: Int) {
+        let x = 0
+        // a comment
+        print(ChangeMe)
+    }
+}
t/t4018/swift-func new file +5 -0
new file mode 100644
index 0000000000..1fecae0911
@@ -0,0 +1,5 @@
+func RIGHT(x: Int) -> Int {
+    let y = x
+    // a comment
+    return ChangeMe
+}
t/t4018/swift-generic-subscript new file +7 -0
new file mode 100644
index 0000000000..423cb58941
@@ -0,0 +1,7 @@
+struct Container {
+    subscript<RIGHT>(index: Int) -> Int {
+        let a = 0
+        // a comment
+        return ChangeMe
+    }
+}
t/t4018/swift-init new file +7 -0
new file mode 100644
index 0000000000..dc7a298f38
@@ -0,0 +1,7 @@
+class Foo {
+    init(RIGHT: Int) {
+        let x = 0
+        // a comment
+        print(ChangeMe)
+    }
+}
t/t4018/swift-inline-attribute new file +7 -0
new file mode 100644
index 0000000000..2374c4b603
@@ -0,0 +1,7 @@
+class Service {
+    @objc func RIGHT() {
+        let path = "/api"
+        // a comment
+        log(ChangeMe)
+    }
+}
t/t4018/swift-modifiers new file +4 -0
new file mode 100644
index 0000000000..9d80685a78
@@ -0,0 +1,4 @@
+public static func RIGHT() -> Int {
+    // a comment
+    return ChangeMe
+}
t/t4018/swift-protocol new file +5 -0
new file mode 100644
index 0000000000..07c39ec2a3
@@ -0,0 +1,5 @@
+protocol RIGHT {
+    var first: Int { get }
+    // a comment
+    var second: ChangeMe { get }
+}
t/t4018/swift-struct new file +5 -0
new file mode 100644
index 0000000000..e399ed7759
@@ -0,0 +1,5 @@
+struct RIGHT {
+    let a = 1
+    // a comment
+    let b = ChangeMe
+}
userdiff.c +10 -0
index b5412e6bc3..7129bf1482 100644
@@ -362,6 +362,16 @@ PATTERNS("scheme",
 	 "\\|([^|\\\\]|\\\\.)*\\|"
 	 /* All other words should be delimited by spaces or parentheses. */
 	 "|([^][)(}{ \t])+"),
+PATTERNS("swift",
+	 "^[ \t]*((@[A-Za-z_][A-Za-z0-9_]*(\\([^()]*\\))?[ \t]+)*([a-z]+[ \t]+)*(func|init|deinit|subscript|class|struct|enum|protocol|extension|actor)[ \t(?!<].*)$",
+	 /* -- */
+	 "[a-zA-Z_][a-zA-Z0-9_]*"
+	 /* hexadecimal, octal, and binary literals */
+	 "|0[xX][0-9a-fA-F_]+|0[oO][0-7_]+|0[bB][01_]+"
+	 /* integers and floating-point numbers */
+	 "|[0-9][0-9_]*([.][0-9_]+)?([eE][-+]?[0-9]+)?"
+	 /* unary and binary operators */
+	 "|[-+*/%<>=!&|^~?]=|&&|\\|\\||<<=?|>>=?|\\?\\?|\\.\\.[.<]|->"),
 PATTERNS("tex", "^(\\\\((sub)*section|chapter|part)\\*{0,1}\\{.*)$",
 	 "\\\\[a-zA-Z@]+|\\\\.|([a-zA-Z0-9]|[^\x01-\x7f])+"),
 { .name = "default", .binary = -1 },

Range-diff against v1:
1: 1e7e199355 ! 1: af48611565 userdiff: add support for Swift
@@ t/t4018/swift-failable-init (new)
@@
+class Bar {
+ init?(RIGHT: Int) {
-+ let value = RIGHT
++ let x = 0
+ // a comment
+ print(ChangeMe)
+ }
@@ t/t4018/swift-func (new)
## t/t4018/swift-generic-subscript (new) ##
@@
+struct Container {
-+ subscript<RIGHT>(index: RIGHT) -> Int {
++ subscript<RIGHT>(index: Int) -> Int {
+ let a = 0
+ // a comment
+ return ChangeMe
@@ t/t4018/swift-init (new)
@@
+class Foo {
+ init(RIGHT: Int) {
-+ let value = RIGHT
++ let x = 0
+ // a comment
+ print(ChangeMe)
+ }
@@ userdiff.c: PATTERNS("scheme",
+ /* integers and floating-point numbers */
+ "|[0-9][0-9_]*([.][0-9_]+)?([eE][-+]?[0-9]+)?"
+ /* unary and binary operators */
-+ "|[-+*/%<>=!&|^~?]=?|&&|\\|\\||<<=?|>>=?|\\?\\?|\\.\\.[.<]|->"),
++ "|[-+*/%<>=!&|^~?]=|&&|\\|\\||<<=?|>>=?|\\?\\?|\\.\\.[.<]|->"),
PATTERNS("tex", "^(\\\\((sub)*section|chapter|part)\\*{0,1}\\{.*)$",
"\\\\[a-zA-Z@]+|\\\\.|([a-zA-Z0-9]|[^\x01-\x7f])+"),
{ .name = "default", .binary = -1 },

Signature · 1 line
2.52.0
#7 lore raw
Quoted 28 lines · Shlok Kulshreshtha

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.

---
v2, addressing Johannes Sixt's review of v1 (<[email protected]>). 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.

Quoted 2 lines

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

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'.

Acked-by
#8 lore raw

Am 21.07.26 um 21:33 schrieb Junio C Hamano:

Quoted 30 lines
Quoted 28 lines · Shlok Kulshreshtha

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.

---
v2, addressing Johannes Sixt's review of v1 (<[email protected]>). 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.

Quoted 7 lines
Quoted 2 lines

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

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'.

This round looks good to me.

-- Hannes

#9 lore raw
In reply to Shlok Kulshreshtha
Quoted 4 lines · Shlok Kulshreshtha

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.

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?

#10 lore raw

Am 27.07.26 um 07:03 schrieb Michael Montalbo:

Quoted 9 lines · Shlok Kulshreshtha
Quoted 4 lines

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.

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?

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

#11 lore raw
Quoted 11 lines · Johannes Sixt

Am 27.07.26 um 07:03 schrieb Michael Montalbo:

Quoted 9 lines · Shlok Kulshreshtha
Quoted 4 lines

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.

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?

[snip]

Quoted 4 lines

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.

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