Tutorial: Put an Access application under source control

You take an existing Access database, turn it into sources in a git repository, build the database from them, and learn the daily cycle: change in Access, commit with one command.

• Windows 11 with the full Microsoft Access installed for your user (requirements).
• The .NET 10 runtime.
• wkl-office on the PATH (installation).
• git on the PATH. This tutorial uses git; for Subversion see Commit what was changed in Access.
• A database to start from; this tutorial uses C:\Data\Customers.accdb. It is only read.

wkl-office new C:\Work\Customers
cd C:\Work\Customers
git init

new writes Customers.acproj, an empty source/ folder, a .gitignore for build/ and obj/, and the tasks of Visual Studio Code. The name of the folder becomes the name of the application; it has to be a VBA identifier.

wkl-office export Customers.acproj -d C:\Data\Customers.accdb

The export works on a copy in a hidden Access and writes every query, module, class, form, report, macro and table schema, the references, the database properties, the theme and the images below source/. It lists every file it wrote. Linked tables are not exported and not warned about: if the database links tables, keep the links in the Linked Tables Manager of WKL Forms Object Library (see Source layout).

Tables are built empty unless their policy says otherwise. Name the tables whose data belongs to the application (lookups, configuration) in Customers.acproj:

<ItemGroup>
  <TablePolicy Include="tblCountries" Policy="SeedData" />
</ItemGroup>

Export again: source/data/tblCountries.jsonl holds its records.

In Access, New project from this database… in the project menu of the add-in does steps 1 to 3 in one dialog (Use the Access add-in).

wkl-office check Customers.acproj
wkl-office build Customers.acproj

check finds invalid sources, missing references, a missing ODBC driver or a password written into a query before Access starts. build makes build/Debug/Customers.accdb from the sources alone.

wkl-office roundtrip Customers.acproj

It builds a copy, exports it and compares the result with the sources. Exit code 0 means: building these sources and exporting the result again writes the same sources (text files compared with line ends unified, other files byte by byte), on this machine. It shows that the sources are stable and that the build takes over everything they describe. It does not show that the sources hold everything the original database had - what the export does not write cannot differ (see What the export does not keep) - nor that the application behaves the same; test the built database for that. Read the warnings of the export: a property it could not keep is reported there, not by the roundtrip. The first run after the export from the old database may report forms and modules that Access writes once in its own way; run wkl-office export Customers.acproj on the built database, and the next roundtrip is clean.

wkl-office commit Customers.acproj -m "Customers: sources from the database"

commit exports the built database once more, adds the project file, .gitignore and source/ to git, and commits. It does not push.

1. Open build\Debug\Customers.accdb in Access and change a form, a query or code. Save.

2. Run wkl-office status Customers.acproj to see what changed. With the Access add-in, you see the same in Access, on the tab Changes of the work area:

   

   A report changed in Access; the next step is the export to the sources.

3. Run wkl-office commit Customers.acproj -m "<what changed>". The export takes the database from the open Access; it refuses while something is unsaved and names it.

When a colleague's changes arrive with git pull, run wkl-office import Customers.acproj --changed to load them into the database open in Access, or close it and run wkl-office build Customers.acproj.

A repository with Customers.acproj and source/, from which wkl-office build makes a working Customers.accdb on any machine with Access, and a daily cycle in which every change made in Access reaches the repository as readable text.

• Command-line reference – Release builds with ACCDE, change tracking, JSON output for CI
• Project file reference – configurations, templates, the finishing function
• Troubleshooting