Skip to main content

Adding custom files to your SDK source code repository

Deprecated

The .codegenignore file is deprecated. Use custom code injection instead: it preserves your custom code across regenerations, works with any file in the SDK (not just files the generator would otherwise delete), and doesn't stop APIMatic from updating generated code. This page stays available for repositories that still rely on a .codegenignore file.

APIMatic doesn't recommend that you manually commit changes to the GitHub repository for your SDK, to avoid conflicts and inconsistencies. However, in certain situations you may need to. For instance, you might want to include unit tests that run after each SDK update.

When APIMatic publishes source code to your GitHub repository, it purges existing files before committing changes. This ensures the removal of any obsolete code files corresponding to schemas that have been removed in the latest API update. Consequently, any files manually committed to the repository are deleted upon the next SDK source code publication.

Use custom code injection instead​

Custom code injection is the supported way to keep custom code in a generated SDK. You add your logic to the generated SDK, save it with apimatic sdk save-changes, and APIMatic reapplies it on every regeneration. Because APIMatic tracks your changes rather than skipping files, generated code keeps receiving updates and the CLI walks you through any conflicts.

It covers every case the .codegenignore file was used for, including new files, extra dependencies, custom authentication providers, unit tests, and GitHub workflows.

The legacy .codegenignore file​

The codegenignore file is a plain text file which allows you to specify a list of files or directories that should be preserved during APIMatic's commits to your SDK repository.

Pattern reference​

.codegenignore is based on the .gitignore specification version 2.42.1

Pattern format​

  • A blank line matches no files, so it can serve as a separator for readability.
  • A line starting with # serves as a comment. Put a backslash (\) in front of the first hash for patterns that begin with a hash.
  • Trailing spaces are ignored unless they're quoted with a backslash (\).
  • An optional prefix ! negates the pattern, so any matching file excluded by a previous pattern becomes included again. You can't re-include a file if a parent directory of that file is excluded. Git doesn't list excluded directories for performance reasons, so any patterns on contained files have no effect, no matter where they're defined. Put a backslash (\) in front of the first ! for patterns that begin with a literal !, for example, \!important!.txt.
  • The slash / is used as the directory separator. Separators may occur at the beginning, middle, or end of the search pattern.
  • If there is a separator at the beginning or middle (or both) of the pattern, then the pattern is relative to the directory level of the particular file itself. Otherwise, the pattern may also match at any level below the .codegenignore level.
  • If there is a separator at the end of the pattern, then the pattern only matches directories. Otherwise, the pattern can match both files and directories. For example, the pattern doc/frotz/ matches the doc/frotz directory but not the a/doc/frotz directory. However, frotz/ matches frotz and a/frotz when the match is a directory. All paths are relative to the .codegenignore file.
  • An asterisk * matches anything except a slash. The character ? matches any one character except /. The range notation, for example [a-zA-Z], matches one of the characters in a range.
  • Two consecutive asterisks (**) in patterns matched against a full pathname may have special meaning:
  • A leading ** followed by a slash means match in all directories. For example, **/foo matches the file or directory foo anywhere, the same as the pattern foo. **/foo/bar matches the file or directory bar anywhere directly under the directory foo.
  • A trailing /** matches everything inside. For example, abc/** matches all files inside the directory abc, relative to the location of the .codegenignore file, with infinite depth.
  • A slash followed by two consecutive asterisks then a slash matches zero or more directories. For example, a/**/b matches a/b, a/x/b, and a/x/y/b.
  • Other consecutive asterisks are considered regular asterisks and match according to the previous rules.

Usage example​

src/
├── MyApi.Standard
├── MyApi.Tests
├── MyApi.sln
├── LICENSE
├── doc
└── README.md

In this scenario, APIMatic published a C# SDK to a GitHub repository while the SDK owner created and committed a Test Project called MyApi.Tests to the same repository branch.

The next SDK update is going to remove the MyApi.Tests Project.

In order to prevent this from happening, the following codegenignore file can be created and committed to the root directory. 

/MyApi.Tests

This will instruct APIMatic’s Code Generator not to delete the MyApi.Tests directory and the files/directories contained within it while committing changes.

Caution​

Be wary of including auto-generated files in your .codegenignore as it will prevent APIMatic from updating them. This may lead to inaccurate SDKs.