Manual use

This guide shows the complete workflow on your own Mac: set up the project, check while developing, check before committing, check before the merge request.

Prerequisites

CodeGuard is installed, the organization policy is set up and codeguard doctor reports ready: true (see Getting started).
Your project is a Git repository and you work in its root directory. check-diff requires the project root and the repository root to be identical.

Step 1: Set up the project

Change to the root directory:
```
cd ~/Developer/MeinProjekt
```
Check what CodeGuard finds there:
```
codeguard doctor
```
compile and tests should be active as soon as there is a Package.swift or Xcode project in the directory. Under platform.* and simulator.* you can see which platforms you can build and test.
Create a .codeguard.yml if needed. You can find examples for each platform under Configuration examples. Validate it:
```
codeguard config validate
```
Optional: Put a .swift-format file in the root directory if your project uses a different style than the swift-format defaults (see Checks and rules).
Grant trust so that CodeGuard may build and test:
```
codeguard trust grant --duration 8h
```
Review the execution surfaces shown before you type yes.
Commit .codeguard.yml and .swift-format so that your team and CI use the same configuration.

caution

Every change to .codeguard.yml invalidates your trust ticket. Run codeguard trust grant again afterwards.

Step 2: Check individual files while developing

check-file is the fastest run. It never builds or tests and needs no trust ticket.

codeguard check-file Sources/App/Session.swift

Real result for a file with try!, as!, fatalError and a logged password:

CODEGUARD_FAILED

6 blocking violations found in 1 changed files.
Validation: file (complete)
Exit: 1 (validation_failed)
Requested: format, security, swiftlint
Completed: format, security, swiftlint
Skipped: 
Tool: swift-format main [tool_swift_format] completed, 9ms, truncated: false
Tool: swiftlint 0.65.1 [tool_swiftlint] completed, 53ms, truncated: false
Run: cg_0ab81208-c7d2-4d65-9e63-3fb0ac640112

1. CRITICAL Sources/SwiftPMClean/Session.swift:8:9
   Rule: sensitive-data-in-log
   Possible password is written to a log.
   Do not log credentials or secrets; log a non-sensitive identifier or omit the value.

2. ERROR Sources/SwiftPMClean/Session.swift:7:22
   Rule: forbidden-force-try
   `try!` can crash the application.
   Handle the error explicitly with `do`/`catch`, or propagate it with `try`.

3. ERROR Sources/SwiftPMClean/Session.swift:7:22
   Rule: swiftlint.force_try
   [force_try] Force tries should be avoided

4. ERROR Sources/SwiftPMClean/Session.swift:9:23
   Rule: forbidden-force-cast
   A forced cast can terminate the process.
   Use a conditional cast (`as?`) and handle the failure case.

5. ERROR Sources/SwiftPMClean/Session.swift:9:23
   Rule: swiftlint.force_cast
   [force_cast] Force casts should be avoided

6. ERROR Sources/SwiftPMClean/Session.swift:13:74
   Rule: forbidden-fatal-error
   `fatalError` terminates the process.
   Throw an error or return a failure result instead of terminating the process.

Next action: Fix the reported violations and run `codeguard check-diff` again.

Fix the findings from top to bottom. Each file:line:column entry takes you to the location.

Step 3: Before committing

Check what you want to commit:

git add Sources/App/Session.swift
codeguard check-diff --staged

Invocation	Which files count as changed
`check-diff --staged`	staged changes (index compared to `HEAD`)
`check-diff`	unstaged changes (working directory compared to index)
`check-diff --base HEAD --include-untracked`	everything since the last commit, including new files not yet added

The working directory is always read

Git only supplies the list of changed files and lines. CodeGuard reads the content from the working directory, and build and tests also use the working directory. If you kept editing after git add, --staged checks the current file content.

check-diff builds and tests (default configuration). A run with simulator tests takes much longer than check-file.

Step 4: Before pushing or opening a merge request

Check all changes on your branch against the target branch, including new files:

git fetch origin
codeguard check-diff --base origin/main --include-untracked

--base compares the given revision with the working directory.
If the reference is missing locally, the run ends with exit 2 (missingBase). A commit SHA whose object is missing is exit 3.
If a name is ambiguous (a branch and a tag with the same name), that is exit 2. Then use the full name, for example refs/remotes/origin/main.

A green run with build and tests of a Swift package:

CODEGUARD_PASSED

0 blocking violations found in 1 changed files.
Validation: file (complete)
Exit: 0 (completed)
Requested: compile, format, security, swiftlint, swiftlint_metrics, tests
Completed: compile, format, security, swiftlint, swiftlint_metrics, tests
Skipped: 
Konfiguration: .codeguard.yml (auto, sha256 5967f32a…)
Tool: swift-format main [tool_swift_format] completed, 9ms, truncated: false
Tool: swiftlint 0.65.1 [tool_swiftlint] completed, 74ms, truncated: false
Tool: swiftlint 0.65.1 [tool_swiftlint_metrics] completed, 74ms, truncated: false
Tool: swift-package-manager 6.4.0-dev [tool_swiftpm_build] completed, 2611ms, truncated: false
Tool: swift-package-manager 6.4.0-dev [tool_swiftpm_test] completed, 3871ms, truncated: false
Run: cg_f5fb110f-22c5-4df5-9dd3-c302dffe4f4b

Watch Completed: only when compile and tests appear there was the project really built and tested.

Step 5: Check the whole project

codeguard check-project

check-project checks all files in paths.include, builds all platforms and runs the tests. This is suitable for a run before a release or at night.

Save reports to a file

mkdir -p build
codeguard --format json  --output build/codeguard.json  check-diff --base origin/main
codeguard --format sarif --output build/codeguard.sarif check-diff --base origin/main

With --output, the console stays empty. The exit code is the same as without --output.
Every invocation is a complete run. Two formats mean two runs, including build and tests.

For your own evaluations with jq:

jq -r '.violations[] | "\(.severity) \(.file // "-"):\(.line // "-") \(.rule)"' build/codeguard.json

Common situations

Message	Cause and solution
`Exit: 6 (security_policy)` with `codeguard-build-execution-denied`	No trust ticket or an invalid one. Check `codeguard trust status`, then run `codeguard trust grant`.
`Exit: 6 (scope_violation)` with `path-outside-allowed-scope`	The file is outside `paths.include` or in `paths.exclude`. Check the path or extend `paths.include`.
`Exit: 6 (protected_file)` with `protected-file-change`	The diff changes a protected file, for example `Package.swift`. This is intended and needs human review.
`Exit: 3` with `codeguard-simulator-selection-failed`	No simulator runtime for the platform. Install the runtime or exclude `tests` with `scopes: []`.
`Exit: 3` with `codeguard-dependency-unavailable`	A tool is missing, or the package has remote dependencies that cannot be loaded offline.
`Konfiguration: Standardwerte (--no-project-config)`	You deliberately turned off the project configuration. Leave out `--no-project-config`.

Prerequisites​

Step 1: Set up the project​

Step 2: Check individual files while developing​

Step 3: Before committing​

Step 4: Before pushing or opening a merge request​

Step 5: Check the whole project​

Save reports to a file​

Common situations​

See also​