Skip to main content

Adding custom files to your SDK Source Code repository

note

This feature is in beta

APIMatic does not recommend that users manually commit any changes to their SDK's GitHub repository to avoid conflicts and inconsistencies. However, in certain situations, users may need to do this. 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 will be deleted upon the next SDK Source Code publication.

In order to prevent custom files from being deleted, you can make use of the .codegenignore file.

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

The .codegenignore file​

.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 are quoted with backslash ("\").
  • An optional prefix "!" which negates the pattern; any matching file excluded by a previous pattern will become included again. It is not possible to 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 are 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 will only match directories, otherwise the pattern can match both files and directories. For example, a pattern doc/frotz/ matches doc/frotz directory, but not a/doc/frotz directory; however frotz/ matches frotz and a/frotz that is a directory (all paths are relative from the .codegenignore file).
  • An asterisk "*" matches anything except a slash. The character "?" matches any one character except "/". The range notation, e.g. [a-zA-Z], can be used to match one of the characters in a range.
  • Two consecutive asterisks ("**") in patterns matched against full pathname may have special meaning:
  • A leading "**" followed by a slash means match in all directories. For example, "**/foo" matches file or directory "foo" anywhere, the same as pattern "foo". "**/foo/bar" matches file or directory "bar" anywhere that is directly under directory "foo".
  • A trailing "/**" matches everything inside. For example, "abc/**" matches all files inside 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", "a/x/y/b" and so on.
  • Other consecutive asterisks are considered regular asterisks and will 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.