--clear-cache: what is cache in rector context? when should we clear?

[realtebo]

I noticed only today in our CI/CD that we are using --clear-cache is 100% of situations where we are using rector.

What is the cache in this context?
When should we clear it and when should we NOT clear it ?

[staabm]

Cache means that rector keeps track of which files have been modified since the last run, so rector is able todo less work by only work on differences. It can be a mean to reduce CI runtime, but might sometime lead to rector missing to refactor some files.

In CI usually there is no caching, if you didn't explicitly configure it: https://getrector.com/documentation/cache-in-ci

[realtebo]

Why?

Rector, as I can see, it's able to understand if a file is changed and so ignore the specific cache.
How can rector fail? in which circumstances?