This is not a myth or a misunderstanding. SuiteCRM and Git are a difficult and often counter-productive combination if SuiteCRM is treated like a typical application repository. This is not a Git problem. It’s an architectural mismatch between how SuiteCRM works and how Git expects software to behave.
1. Auto-generated files everywhere
SuiteCRM:
- regenerates files automatically
- rebuilds metadata
- generates PHP code from Admin UI actions
Git strongly assumes that files change because a developer intentionally changed them.
Result: git status is constantly full of changes that no one explicitly wrote.
2. The custom/ directory is not “clean source code”
In theory, custom/ is the safe place. In practice, it contains:
- runtime-generated metadata
- files recreated by Repair & Rebuild
- Admin-UI-driven configuration output
So custom/ is not just source code. It is source code + application state mixed together. This breaks a core Git assumption.
3. Environment-specific noise
Many files are environment-dependent:
config.php,config_override.php- cached language files
- vardefs and relationship metadata
- system-generated PHP
Git cannot distinguish:
- intentional changes
- deployment artifacts
- runtime side effects
This leads to meaningless diffs and risky commits.
4. SuiteCRM is not a typical framework
SuiteCRM is simultaneously:
- a framework
- a CMS
- a runtime code generator
Key problem:
- there is no clean separation between source → build → runtime
- the application rewrites itself
- Admin users effectively act as code generators
Git assumes deterministic builds.
SuiteCRM is not deterministic.
5. Team workflows break down quickly
In a team:
- two people change Admin settings
- different PHP files are regenerated
- Git sees conflicts in auto-generated files
The conflicts are often:
- hard to understand
- not logically mergeable
- unrelated to real business logic
The Core Conceptual Problem
SuiteCRM was not designed with “version control first” in mind.
It was designed for:
- on-server configuration
- Admin-driven customization
- long-running mutable installations
Git was designed for:
- immutable source code
- reproducible builds
- CI/CD pipelines
These two philosophies clash.
When SuiteCRM and Git Work Well
They work very well when SuiteCRM is treated as a platform, not as an app.
What should be in Git
- logic hooks (
custom/modules/**/logic_hooks.php) - custom action classes
- integrations (APIs, webhooks, middleware)
- only developer-written code
- upgrade-safe extensions
What should not be in Git
- cache directories
- auto-generated vardefs
- relationship metadata
- Admin-generated configuration files
- environment-specific config and secrets
The Correct Mindset
With SuiteCRM:
You do not version the installation.
You version the behavior you add to it.
In other words:
“This is the business logic we inject into the system”
not
“This is the full internal state of the CRM”
Conclusion
SuiteCRM + Git is a difficult combination. This is not a mistake, but a design mismatch. Git works perfectly when limited to custom business logic. Trying to version the entire SuiteCRM installation leads to chaos.