The optimal approach for organizing IBM i source code (e.g., RPG, COBOL, CL) with Visual Studio Code (VS Code) and Git involves migrating from traditional source physical files to stream files in the Integrated File System (IFS). This enables seamless version control, collaboration, and modern tooling.
The IFS treats source as plain text files in a Unix-like directory structure, making it Git-friendly and accessible via VS Code's SSH-based extensions.
Below, I'll outline the recommended method, drawing from established best practices
STEP 1 - Migrate Traditional Source Files to IFS Stream Files
Why?
Traditional source physical files (e.g., QRPGSRC, QDDSSRC, QCLSRC in a library) are not natively compatible with Git's file-based tracking. IFS stream files allow direct Git operations, easier editing in VS Code, and cross-platform access.
How?
- Use tools like Rational Developer for i (RDi) or scripts (e.g., CPYSRCF to copy members to IFS) to export source members as text files.
- Store in IFS directories under / (root), such as /QOpenSys or custom paths like /home/dev/source.
- For compilation, use commands with the SRCSTMF parameter (e.g., CRTBNDRPG SRCSTMF('/path/to/file.rpgle')), supported in IBM i 7.4+ for most languages.
Tip: Start with new projects; for legacy systems, migrate incrementally to avoid disruption.
Step 2 - Plan and Organize the new IFS Layout
Organize files hierarchically for clarity, scalability, and logical grouping.
Avoid flat structures, super busy folders are hard to navigate so use folders to separate by application, type, or function.
This mirrors modern repo patterns and works well with VS Code's file explorer.
Level | Example Path | Purpose | Files/Examples |
|---|---|---|---|
Project Root | /myproject/ | Top-level repo container | N/A |
Source by Language | /myproject/source/rpg/ /myproject/source/cl/ /myproject/source/sql/ | Group by code type for easy filtering in VS Code | inventory.rpgle update.clle create_table.sql |
Logical Grouping | /myproject/apps/inventory/programs/ /myproject/apps/inventory/data/ | Group by business function (preferred for large apps) | item_maint.rpgle in programs; DDL scripts in data |
Elements | /myproject/build/ /myproject/config/ | Scripts and non-source assets | compile_all.sh, db_setup.sql |
List Element | /myproject/tests/ | Unit/integration tests | test_inventory.rpgle |
Please note that meaningful folder names improve navigation for teams, especially juniors, noobs or just folks who have maybe only ever used traditional source files.
Use submodules for modular apps (e.g., shared utilities). Maintain consistent naming (e.g., lowercase, kebab-case for files).
VS Code Integration: With the "code-for-ibmi" extension pack, and it's Prjoect Explorer, browsing the IFS like a local filesystem is easier and clearer than ever!
What about Git?
Repository Setup and Workflow
Initialize Repo First: In VS Code, open the IFS folder, then use the built-in Source Control view to git init. Or clone from a remote (e.g., GitHub) to your local machine and sync to IFS via rsync or extensions.
Research GIT's Branching Strategy and adopt Git Flow for IBM i's release cycles:
- main: Stable production code.
- develop: Integration branch.
- Feature branches (e.g., feature/inventory-update) for tasks; merge via pull requests (PRs) after local builds/tests.
- Short-lived branches to minimize conflicts in concurrent editing.
Commits are Important: Commit frequently with descriptive messages (e.g., "feat: add item validation in inventory.rpgle"). Include all source types, but use build scripts for compiled objects (e.g., *PGM, *SRVPGM)—don't version binaries. Now, when your teammates are also committing/syncing frequently you are all seeing the latest versions ion your local copies.
Handle Non-Source Files as well. You can store database defs as SQL scripts; use Git LFS for large files like backups.
Essential Configurations for Git and your Team
.gitignore for IBM i Exclude environment-specific or temp files to keep repos clean. Here's a tailored template:
*.logs
.evfevent
.env
# VS Code
.vscode/*
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/launch.json
*.code-workspace
# History and credentials
.history/
**/credentials.json
*password*
node_modules/
# IBM i specifics
*.dat
*.csv
*.json # Unless project-specific
This prevents deploying junk and respects builds/deployments.
Access and Security
Set IFS permissions (*READ/*WRITE/*EXECUTE) per user/group. Use SSH keys for VS Code connections.
Best Practices and Personal Recommendations
Tools/Extensions: Install "IBM i Development Pack" in VS Code for syntax highlighting, debugging, and Git integration. Consider ARCAD Elias for "project mode" (clones full repo to local sandbox for offline work).
Collaboration: Enable concurrent edits with optimistic locking; use PRs for reviews.
Documentation & Backups: Document structure in README.md. Automate backups of IFS dirs.
Pitfalls to Avoid: Don't force traditional pessimistic locks into Git—embrace branches for parallelism. Skip open-source builds without IBM i adaptations.
This method streamlines development, reduces errors, and scales for teams. For hands-on setup, start with VS Code's IBM i extensions and a small pilot migration.