Ignoring files

Ignoring files removes matched files from the generation process and grants full ownership of those files. This approach can address bugs, add features, or implement workarounds that are not supported by the source API or generator configuration. In Speakeasy, this includes modifying generated SDK code, documentation, or examples.

For most persistent changes to generated SDKs, the Custom code feature is recommended. Custom code uses a three-way merge to preserve edits across generations.

Ignoring files increases maintenance effort and can introduce inconsistencies, failures, and discrepancies within SDKs. The trade-offs should be evaluated carefully, as this approach can add significant overhead.

Recommended use cases

Ignoring files can be beneficial in low-impact scenarios such as:

• Customizing usage snippets or example code.
• Modifying generated documentation.
• Implementing additional business logic that the API does not handle.

When possible, avoid ignoring core generated code or package dependencies, because these changes can introduce issues during SDK generation or result in failures.

Mark files with .genignore

To ignore files, add a .genignore file to the project. This file behaves similarly to .gitignore but signals that the files it matches are managed manually rather than by the SDK generator.

Rules in .genignore follow this syntax:

• Blank lines match nothing and improve readability.
• Lines starting with # are comments. Escape # with a backslash (\#) to match a file starting with #.
• Trailing spaces are ignored unless escaped with \, which preserves spaces.
• Lines starting with ! denote negative matches (files matching that line will not be ignored).
• Lines ending with / match directories only.
• Each non-empty, non-comment line is interpreted as a glob pattern (for example, *.go matches all .go files).
• Wildcards (*, ?) do not match directory separators.
• ** matches across multiple directory levels.
• Lines starting with / match paths relative to the directory that contains the .genignore file.

Once a file is included in .genignore, the generator does not modify that file.

Files generated by Speakeasy include the following header:

// Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.

To mark a file as manually maintained, update the header to:

// Code originally generated by Speakeasy (https://speakeasy.com).

This header distinguishes manually maintained files from files that continue to be managed by the generator.

Caveats

Ignoring files can introduce the following issues:

• Duplicated code: Changes in naming conventions during generation can result in duplicate symbols between ignored files and generated code.
• Missing code: Internal generator changes can replace or rename symbols, causing ignored files to break.
• Dead code: Ignored files may become obsolete if they are no longer referenced by the SDK, resulting in unused code.

Each SDK generation can introduce these or other maintenance challenges. Ignore files only when necessary.

Recovering from issues

The following workflow can help resolve issues caused by ignored files:

• Comment out the affected lines in .genignore.
• Regenerate the SDK using the Speakeasy CLI or GitHub Action.
• Compare changes between the regenerated SDK and the ignored files using git diff.
• Update the ignored files as required, then uncomment or restore the relevant lines in .genignore.
• Commit changes to maintain synchronization between ignored files and the generated SDK.