From c41f026cd6df95e98667934e4895678dae28e11f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Mart=C3=AD?= Date: Thu, 25 Apr 2024 09:40:54 +0100 Subject: [PATCH] README: clarify that we have no plans to exclude files or packages This is a common question in the issue tracker: #631, #777, #802, #844. While here, tweak the wording and formatting in the section as well. --- README.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index bd20bde9..20a09c64 100644 --- a/README.md +++ b/README.md @@ -157,11 +157,11 @@ to document the current shortcomings of this tool. be required by interfaces. This area is a work in progress; see [#3](https://github.com/burrowers/garble/issues/3). -* Garble aims to automatically detect which Go types are used with reflection, - as obfuscating those types might break your program. +* Garble automatically detects which Go types are used with reflection + to avoid obfuscating them, as that might break your program. Note that Garble obfuscates [one package at a time](#speed), so if your reflection code inspects a type from an imported package, - and your program broke, you may need to add a "hint" in the imported package: + you may need to add a "hint" in the imported package to exclude obfuscating it: ```go type Message struct { Command string @@ -172,13 +172,20 @@ to document the current shortcomings of this tool. var _ = reflect.TypeOf(Message{}) ``` +* Aside from `GOGARBLE` to select patterns of packages to obfuscate, + and the hint above with `reflect.TypeOf` to exclude obfuscating particular types, + there is no supported way to exclude obfuscating a selection of files or packages. + More often than not, a user would want to do this to work around a bug; please file the bug instead. + * Go programs [are initialized](https://go.dev/ref/spec#Program_initialization) one package at a time, where imported packages are always initialized before their importers, and otherwise they are initialized in the lexical order of their import paths. Since garble obfuscates import paths, this lexical order may change arbitrarily. * Go plugins are not currently supported; see [#87](https://github.com/burrowers/garble/issues/87). -* Garble requires `git` to patch the linker. That can be avoided once go-gitdiff supports [non-strict patches](https://github.com/bluekeyes/go-gitdiff/issues/30). + +* Garble requires `git` to patch the linker. That can be avoided once go-gitdiff + supports [non-strict patches](https://github.com/bluekeyes/go-gitdiff/issues/30). ### Contributing