When you initialize a new Grace project using grace init, or when you structure a project manually, Grace expects a certain directory layout. This standardized structure helps keep your workflow definitions, source code, and Grace's operational outputs organized and predictable.

A typical Grace workflow workspace looks like this:

your-workflow-name/
├── .grace/               # Internal directory for Grace's operational files
│   ├── deck/             # Stores JCL generated by 'grace deck'
│   └── logs/             # Stores logs & summaries from 'grace run / grace submit'
├── src/                  # Your application source code (COBOL, PL/I, etc.)
└── grace.yml             # Your declarative workflow definition

Understanding each component will help you effectively manage and version your Grace projects.

Key components

Explore the purpose and contents of each part of the Grace workspace.

grace.yml

The primary configuration file where you define your workflow, jobs, datasets, and toolchain settings.

src/

The conventional location for your application source code that Grace will manage and upload.

.grace/deck/

The internal directory used by Grace for its generated JCL.

.grace/logs/

The internal directory used by Grace for its operational log ouputs.

Best practices

Version control: It's highly recommended to commit your grace.yml and the contents of your src/ directory to a version control system like Git.
.gitignore: The .grace/ directory (and its subdirectories deck/ and logs/) are typically generated by Grace and can often be added to your .gitignore file, as they can be reproduced by running grace deck or grace run. However, you might choose to commit .grace/deck/ if you manually fine-tune JCL there and use grace deck --no-compile.
Clarity: Maintaining this structure makes it easier for team members to understand and contribute to Grace workflows.