# About transformers

A DeepSource Transformer automatically 'transforms' all incoming source code in a repository with popular code auto-formatters (e.g., black, gofmt, etc.).

Whenever a PR is created, all transformers enabled in .deepsource.toml are run and the changes detected - if any - are committed back to that branch.

If changes are introduced without a PR (i.e. committed directly into the default branch), a new PR is created with transformations.

Note

Since GitHub restricts creating commits on branches from other forks, it is not possible to commit back the changes. In this case, we recommend to merge the PR as is. Once merged, DeepSource would automatically pick up the transformations introduced in the merge commit, and create a new PR with these formatting changes only.

When transformers are first introduced in .deepsource.toml (in default branch), the entire code base is transformed. Afterwards, only the files which are added/updated in a commit/PR/MR are transformed.

For PRs which have non-default branches as base (e.g., PRs to release branches, etc.), transformations are not run.

The following table lists all supported transformers and their shortcodes.

Transformer Shortcode
Autopep8 autopep8
Black black
Isort isort
Go Fmt gofmt
Prettier prettier
RuboCop rubocop
StandardJS standardjs
StandardRB standardrb
Yapf yapf

# FAQ

# How do I enable Transformers?

Add an entry in transformers table in .deepsource.toml with the name of the transformer and enabled = true.

e.g. to add black:

[[transformers]]
    name = "black"
    enabled = true

If you don't like to type TOML by hand, go to Settings -> "Generate Configuration" and select the ones you'd like to add from the list.

# Our project doesn't use any code formatter right now, but we want to start using one. What do we do?

When transformers are first introduced in .deepsource.toml (in default branch), the entire code base is transformed and a PR/MR is raised with all the changes. Once that is merged, the entire code base conforms to the style.

# How to specify additional configuration to formatters?

If you have a configuration file for the formatter/linter (pyproject.toml for black, .style.yapf for yapf, etc.), we already respect it. However, the beta version doesn't support supplying meta-configuration options via .deepsource.toml (yet!).

Then onward, for each new commit/PR/MR, all incoming code would automatically be formatted.

# We are an open source project and use fork+PR workflow. Is this suitable for us?

Yes, yes! We support this workflow. There's a minor annoyance that GitHub won't let us update PRs from other forks -- We have mitigated this by transforming the merge commit and not the PR itself. In fact, in this case, our status checks on GitHub would recommend that you merge this PR directly:

GitHub Check Skipped

# If I'm using Transformers, do I need to add the code formatter as a dependency to my project?

It's entirely up to you. If you want to encourage your developers to use it locally, and push only then -- yes, add it as a dev-dependency by all means. But, as far as DeepSource is concerned, you can leave your dependencies as is.

# Can I use Transformers without turning on Analysis?

It's required to have at least a single DeepSource analyzer enabled to be able to use Transformers.

Last Updated: 10/17/2020, 1:48:35 PM