Frequently asked questions (FAQ)

Does OpenRewrite collect any data from our projects?

No. The rewrite-maven-plugin and rewrite-gradle-plugin run locally on your machine, without any connections to Moderne or OpenRewrite. The plugins calls out to Maven Central (or a locally configured mirror) to check for new dependencies. Other than that, you should not see any other outbound traffic.

What is the difference between OpenRewrite and Moderne?

Is it possible to update only a few files with a recipe rather than all of them?

Yes. There are two main options for this:

1. (Recommended) Use some of the common preconditions to limit the files or directories the recipe runs on.

2. Use exclusions to limit the folders the recipe can run on:

Exclusion paths are relative to the project root, not the system file path.

Gradle

In your build.gradle file:

rewrite {
    exclusions = ["folderA", "folderB"]
}

Maven

In the command line:

mvn rewrite:run -Drewrite.exclusions="folderA,folderB"

Is it possible to apply recipes on a step-by-step basis (pausing after certain recipes, so smaller commits can be made)?

This question comes up a lot with bigger migration recipes such as the Migrate to Java 17 recipe. Before we dive into the options you have, it's important to note that OpenRewrite recipes are highly hierarchical in nature. When you execute the Java 17 recipe, you're actually executing 180 individual migration recipes. Some of these recipes are partial steps, that by themselves, would not make sense. Consider, for instance, how different recipes change imports versus add a dependency; you'd need both for the change to make sense, and committing just a part of that would lead to failing intermediate steps.

This nuance is why we don't support intermediate steps to commit results; it would simply be too much to handle feasibly. Furthermore, we'd have to write out to disk repeatedly, which would slow the migration down even more.

That being said, there are two things you can do:

1. You can run individual parts of the hierarchy. For instance, the Migrate to Java 17 recipe contains the Migrate to Java 11 recipe, which contains the Migrate to Java 8 recipe. You could run each of those child recipes and commit the results - which would limit the number of changes being done at a time.

2. You can also use Preconditions to limit the changes to a particular source set or set of files.

Using these two approaches together in separate runs means you can likely create something that's feasible to review.

Worth noting, though, is that each recipe run will need to build up the Lossless Semantic Tree (LST) – which can take some time (especially for larger projects). If you'd like to speed that up, you can have a look at Moderne where we allow you to use precomputed LSTs.

I'm getting java.lang.OutOfMemoryError: Java heap space when running OpenRewrite.

You can either increase the size of the Java heap or build and run recipes with the Moderne CLI.

Java heap instructions

Gradle

gradle -Dorg.gradle.jvmargs=-Xmx8G rewrite:run

Maven

export MAVEN_OPTS="-Xmx8G"
mvn rewrite:run

Moderne CLI

The Moderne CLI builds the LST artifacts for your repository in pieces if the repository can't fit into memory entirely. It also allows you to run recipes against multiple repositories at once.

My recipe appears to hang when running. What's happening? Is there a progress report?

OpenRewrite is likely building up a model of your code and resolving types – this can take a while. Right now, there is not a progress report for recipe runs. However, there is a suggestion to add progress indicators that you can +1 here.

Can I create a report or summary of the changes made through OpenRewrite?

Yes. Take a look at the getting started with data tables guide. Right now, data tables can only be accessed through the Moderne platform. Access to these will be made available through the Maven and Gradle plugin soon.

I want to exclude a single recipe from a collection of recipes.

This is not possible right now and doing so would be quite complicated. For a detailed explanation as to why, check out this post.

Is it possible to pass arguments to a recipe from the command line? I want to programmatically configure complex recipes.

Not right now. This is a particularly difficult problem to address for a couple of reasons:

• Some recipes can be composed of other recipes which could then include other recipes composed of other recipes and so on.

• Some recipes can be used multiple times in one recipe with different parameters such as in this example.

There is an open issue for this request that you can +1 or provide feedback on.

What order do recipes run in?

Recipes are run in the order they are activated.

Let's take this example snippet of a build.gradle file:

rewrite {
    activeRecipe(
        'com.yourorg.Foo',
        'com.yourorg.RecipeA'
    )
}

and this example of a rewrite.yml file:

---
type: specs.openrewrite.org/v1beta/recipe
name: com.yourorg.RecipeA
displayName: Recipe A
description: Applies Recipe B.
recipeList:
  - com.yourorg.RecipeB
  - com.yourorg.RecipeC
---
type: specs.openrewrite.org/v1beta/recipe
name: com.yourorg.Foo
...
recipeList:
  - com.yourorg.bar
  - com.yourorg.bash

In this example, the recipes would be run in this order:

1. com.yourorg.Foo

2. com.yourorg.bar

3. com.yourorg.bash

4. com.yourorg.RecipeA

5. com.yourorg.RecipeB

6. com.yourorg.RecipeC