Is this page helpful?

Git Configuration Reference#

Overview#

This reference provides technical specifications for how AI Workbench configures and uses Git.

Use this reference to understand:

Project layout schema and field definitions
How storage types map to Git configuration files
Git LFS initialization and setup
Git hooks installed by AI Workbench
Project registration requirements
Manual configuration options

For conceptual understanding of version control, see Version Control in AI Workbench.

For step-by-step procedures, see How to Use Version Control.

For Git operation behavior and feature support, see Version Control Reference.

Key Concepts#

Layout Section: The section in spec.yaml that declares directory structure and Git tracking behavior for project paths.
Storage Type: A field in the layout section that determines how files are tracked (git, gitlfs, or gitignore).
Configuration Generation: The process where AI Workbench reads the layout section and creates or updates .gitattributes and .gitignore files.
Project Registration: The process that adds a project to AI Workbench’s inventory so it appears in the UI.

Requirements#

System Requirements#

Git must be installed on the system
Git LFS must be installed for projects using LFS storage
Global Git configuration (user.name, user.email) must be set

Git Configuration#

AI Workbench requires global Git author information:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

This configuration applies to all projects across all locations.

Project Layout Schema#

Overview#

The layout section in spec.yaml declares how directories are tracked in Git.

AI Workbench reads this section and generates .gitattributes and .gitignore files accordingly.

Layout Field Definitions#

Each entry in the layout section contains three fields:

Field	Description
path	Directory path relative to project root. Must end with trailing slash for directories. Example: code/, data/, data/scratch/.
type	Semantic label for the directory’s purpose. Valid values: `code`, `data`, `models`. This field is descriptive and does not affect Git behavior.
storage	Git tracking strategy. Valid values: `git` (normal tracking), `gitlfs` (Git LFS tracking), `gitignore` (excluded from Git). This field determines what configuration files are generated.

Example Layout Section#

layout:
    - path: code/
      type: code
      storage: git

    - path: models/
      type: models
      storage: gitlfs

    - path: data/
      type: data
      storage: gitlfs

    - path: data/scratch/
      type: data
      storage: gitignore

Storage Type Mappings#

How Storage Values Generate Git Configuration#

Storage Type	Configuration File	Behavior
`git`	None (default Git)	Files tracked normally with Git. No special configuration needed.
`gitlfs`	`.gitattributes`	Pattern added to .gitattributes with LFS filters. Files stored as LFS pointers in Git, actual content stored separately. Downloaded on-demand.
`gitignore`	`.gitignore`	Pattern added to .gitignore. Files excluded from Git entirely. Not tracked, committed, or pushed.

Configuration Generation Process#

When you create or open a project:

AI Workbench reads the layout section from spec.yaml
For each storage: gitlfs entry, adds pattern to .gitattributes
For each storage: gitignore entry, adds pattern to .gitignore
Initializes Git LFS if any gitlfs entries exist
Git LFS installs standard hooks (post-checkout, post-commit, post-merge, pre-push)

Generated Configuration Files#

.gitattributes#

Purpose: Specifies Git LFS tracking patterns

Generation: AI Workbench generates patterns for paths with storage: gitlfs

Example content:

models/** filter=lfs diff=lfs merge=lfs -text
data/** filter=lfs diff=lfs merge=lfs -text

Pattern format:

filter=lfs - Content stored in LFS
diff=lfs - LFS-aware diffs
merge=lfs - LFS-aware merges
-text - Mark as binary (don’t perform line ending conversion)

Customization: You can manually edit .gitattributes to add or modify patterns. Changes take effect immediately for new files. Existing tracked files require migration.

.gitignore#

Purpose: Specifies files excluded from Git tracking

Generation: AI Workbench generates patterns from multiple sources:

Workbench metadata exclusions
Layout entries with storage: gitignore
Standard development tool ignores (Python, Jupyter, etc.)

Example content:

# Ignore generated or temporary files managed by the Workbench
.project/*
!.project/spec.yaml
!.project/configpacks

# General ignores
.DS_Store

# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

# Temp directories, notebooks created by jupyterlab
.ipynb_checkpoints
.Trash-*/
.jupyter/
.local/

# Workbench Project Layout
data/scratch/*

Workbench metadata exclusions:

.project/* - Excludes all Workbench runtime files
!.project/spec.yaml - But includes the project specification
!.project/configpacks - And includes configpacks directory

Customization: You can manually edit .gitignore. Changes take effect immediately. Files already tracked remain tracked until explicitly removed.

.git/config#

Purpose: Repository-level Git configuration

LFS initialization: When Git LFS is initialized, this section is added:

[lfs]
        repositoryformatversion = 0

Other configuration: AI Workbench does not modify other sections of .git/config. Remote URLs, branches, and other settings are managed through standard Git commands.

Project Directory Structure#

Example directory structure showing configuration files:

project-root/
├── .git/
│   ├── config                  (has [lfs] section if LFS used)
│   └── hooks/                  (Git LFS standard hooks)
│       ├── post-checkout
│       ├── post-commit
│       ├── post-merge
│       └── pre-push
├── .gitattributes              (LFS patterns: models/**, data/**)
├── .gitignore                  (Workbench + layout ignores)
├── .project/
│   └── spec.yaml               (contains layout section)
├── code/                       (storage: git)
├── data/                       (storage: gitlfs)
│   └── scratch/                (storage: gitignore)
└── models/                     (storage: gitlfs)

Project Registration#

Registration Process#

AI Workbench requires projects to be created or cloned through AI Workbench.

When you create or clone a project via AI Workbench:

Standard Git repository is initialized or cloned
Project layout directories are created with .gitkeep files
.gitattributes and .gitignore are generated from layout section
Git LFS is initialized if layout contains gitlfs entries
Entry is added to $HOME/.nvwb/inventory.json
Project runtime metadata folder is created

Registration Metadata#

inventory.json location: $HOME/.nvwb/inventory.json

Contains project metadata including:

Project name and path
Creation timestamp
Location (local or remote)

Runtime metadata folder: Created alongside project directory or in Workbench storage

Contains:

Container build artifacts
Application state
Temporary files

Why Registration Is Required#

Projects must be registered to appear in AI Workbench UI. Registration creates the necessary metadata and directory structure.

Projects cloned with ``git clone`` outside AI Workbench:

Will NOT be registered
Cannot be opened in AI Workbench
Will not appear in project list

Solution: Always use nvwb clone or the Desktop App Clone button. Once registered, use any Git client for subsequent operations.

Git LFS Configuration#

Automatic LFS Setup for New Projects#

When you create a new project, AI Workbench automatically configures Git LFS.

Default layout includes:

layout:
    - path: models/
      type: models
      storage: gitlfs

    - path: data/
      type: data
      storage: gitlfs

This generates .gitattributes patterns:

models/** filter=lfs diff=lfs merge=lfs -text
data/** filter=lfs diff=lfs merge=lfs -text

LFS Initialization Process#

When a project has storage: gitlfs entries:

AI Workbench runs git lfs install in the repository
[lfs] section is added to .git/config
Git LFS installs four standard hooks in .git/hooks/
.gitattributes patterns are created
Directories are created with .gitkeep files

LFS for Cloned Projects#

Projects cloned from external sources may or may not have LFS configured.

If the remote project uses LFS:

AI Workbench respects existing .gitattributes configuration
Git LFS downloads pointer files as needed
No additional LFS setup required

If the remote project does not use LFS:

Large files are handled as normal Git objects
No LFS configuration is applied automatically
You can manually configure LFS by editing .gitattributes

LFS Storage Limits#

Warning

Git hosting providers have different LFS storage limits and pricing. Exceeding limits may prevent push operations or incur charges.

Provider limits:

GitHub: 1 GB free storage, 1 GB free bandwidth per month
GitLab: 10 GB free storage per project
Bitbucket: 1 GB free storage

Check your provider’s current LFS policies before storing large files.

Customizing LFS Patterns#

To track additional file types with LFS, edit .gitattributes:

# Workbench defaults
models/** filter=lfs diff=lfs merge=lfs -text
data/** filter=lfs diff=lfs merge=lfs -text

# Custom additions
*.h5 filter=lfs diff=lfs merge=lfs -text
*.pkl filter=lfs diff=lfs merge=lfs -text
*.zarr/** filter=lfs diff=lfs merge=lfs -text

Migration of existing files to LFS:

If you add patterns for files already tracked in Git, you must migrate them:

git lfs migrate import --include="*.h5"

Disabling LFS for specific paths:

To exclude a subdirectory from LFS even if parent is tracked:

data/** filter=lfs diff=lfs merge=lfs -text
data/scratch/** -filter -diff -merge

Git Hooks#

Hooks Installed by AI Workbench#

AI Workbench does NOT install custom Git hooks.

All hooks in .git/hooks/ are standard Git LFS hooks, installed by Git LFS during initialization.

Standard LFS Hooks#

Four hooks are installed when Git LFS is initialized:

Hook	Purpose
post-checkout	Downloads LFS objects after checking out a branch or commit. Ensures working directory has LFS file content.
post-commit	Updates LFS tracking information after creating a commit.
post-merge	Downloads LFS objects after merging branches. Ensures merged content is available.
pre-push	Uploads LFS objects before pushing to remote. Ensures LFS content is available to other users.

Hook Content Example#

All LFS hooks follow the same pattern:

#!/bin/sh
command -v git-lfs >/dev/null 2>&1 || {
  printf >&2 "\n%s\n\n" "This repository is configured for Git LFS but 'git-lfs' was not found on your path. If you no longer wish to use Git LFS, remove this hook by deleting the 'post-checkout' file in the hooks directory (set by 'core.hookspath'; usually '.git/hooks')."
  exit 2
}
git lfs post-checkout "$@"

Key points:

Checks if git-lfs is installed
Exits with error if git-lfs is missing
Delegates to git lfs <hook-name> for actual work

Custom Hooks#

You can add custom hooks alongside LFS hooks.

To add custom hooks:

Create or edit hook files in .git/hooks/
Make them executable: chmod +x .git/hooks/my-hook
Ensure they do not conflict with LFS hook behavior

Example: Adding custom pre-commit checks

Create .git/hooks/pre-commit:

#!/bin/sh
# Run linter before commit
python -m pylint src/
exit $?

AI Workbench will not interfere with custom hooks.

Global Git Configuration#

How AI Workbench Uses Global Config#

AI Workbench inherits Git configuration from the system.

Global Git settings apply to all projects across all locations.

Required Configuration#

Author information must be configured:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Without this configuration, commits will fail.

Configuring via Command Line#

Set configuration using git config:

# Set author name
git config --global user.name "Jane Developer"

# Set author email
git config --global user.email "jane@example.com"

# View current configuration
git config --global --list

Configuring via AI Workbench UI#

Desktop App provides UI for Git author configuration:

Open Workbench Settings
Navigate to Git Author section
Enter your name and email
Changes are saved to global Git config

Configuration applies to all projects immediately.

Per-Project Configuration#

AI Workbench does not support per-project Git config via UI.

To set project-specific configuration, use Git directly:

cd /path/to/project
git config user.name "Different Name"
git config user.email "different@example.com"

Project-specific config overrides global config for that project only.

Configuration Workflow#

Complete Workflow from Layout to Git#

Step-by-step process:

User defines layout in spec.yaml

layout:
    - path: code/
      type: code
      storage: git
    - path: models/
      type: models
      storage: gitlfs
    - path: data/scratch/
      type: data
      storage: gitignore

AI Workbench reads layout on project create or open
- Parses spec.yaml
- Identifies storage types
- Determines what configuration files to generate
Configuration files are generated or updated
- .gitattributes gets patterns for storage: gitlfs
- .gitignore gets patterns for storage: gitignore
- Existing patterns are preserved, new ones added
Git LFS is initialized if needed
- Runs git lfs install in repository
- Adds [lfs] section to .git/config
- Git LFS installs its four standard hooks
Directories are created
- Layout paths are created as directories
- .gitkeep files added to empty directories
- Ensures directories are tracked by Git
Everything else is standard Git
- No proprietary extensions
- No command interception
- External Git clients work normally

When Configuration Is Applied#

Configuration generation occurs:

When creating a new project
When cloning a project (initial setup)
When opening an existing project (validation)

Configuration is NOT regenerated:

On every project start
When switching branches
During normal Git operations

Manual edits to .gitattributes and .gitignore are preserved. AI Workbench only adds or updates Workbench-managed sections.

Manual Configuration Customization#

Editing .gitattributes#

You can manually edit .gitattributes to customize LFS behavior.

To add custom LFS patterns:

# Workbench-generated patterns
models/** filter=lfs diff=lfs merge=lfs -text
data/** filter=lfs diff=lfs merge=lfs -text

# Your custom patterns
*.weights filter=lfs diff=lfs merge=lfs -text
experiments/large-outputs/** filter=lfs diff=lfs merge=lfs -text

Changes take effect:

Immediately for new files
Existing files require migration: git lfs migrate import --include="*.weights"

Editing .gitignore#

You can manually edit .gitignore to exclude additional files.

Best practice: Add custom ignores at the bottom:

# Workbench Project Layout
data/scratch/*

# Custom project-specific ignores
experiments/failed-runs/
.vscode/
*.tmp

Changes take effect:

Immediately for untracked files
Already-tracked files remain tracked
To untrack: git rm --cached <file>

Relationship Between spec.yaml and Manual Edits#

Manual edits to .gitattributes and .gitignore take precedence.

AI Workbench:

Reads spec.yaml layout section
Generates initial configuration files
Does NOT overwrite manual changes to those files
Only updates Workbench-managed sections if layout changes

Example scenario:

AI Workbench generates .gitattributes with models/** pattern
You manually add *.pkl pattern
You modify spec.yaml layout (add new path)
AI Workbench adds new pattern but preserves your *.pkl pattern

Your manual edits are safe.

When to Modify spec.yaml vs Configuration Files#

Modify spec.yaml layout when:

Adding new project directories
Changing storage strategy for directories
Setting up project structure for other users

Modify .gitattributes/.gitignore when:

Adding file type patterns
Excluding specific files or paths
Making one-time adjustments

Both approaches work. spec.yaml is declarative and version-controlled. Manual edits are flexible and immediate.

Git Configuration Reference#

Overview#

Key Concepts#

Requirements#

System Requirements#

Git Configuration#

Project Layout Schema#

Overview#

Layout Field Definitions#

Example Layout Section#

Storage Type Mappings#

How Storage Values Generate Git Configuration#

Configuration Generation Process#

Generated Configuration Files#

.gitattributes#

.gitignore#

.git/config#

Project Directory Structure#

Project Registration#

Registration Process#

Registration Metadata#

Why Registration Is Required#

Git LFS Configuration#

Automatic LFS Setup for New Projects#

LFS Initialization Process#

LFS for Cloned Projects#

LFS Storage Limits#

Customizing LFS Patterns#

Git Hooks#

Hooks Installed by AI Workbench#

Standard LFS Hooks#

Hook Content Example#

Custom Hooks#

Global Git Configuration#

How AI Workbench Uses Global Config#

Required Configuration#

Configuring via Command Line#

Configuring via AI Workbench UI#

Per-Project Configuration#

Configuration Workflow#

Complete Workflow from Layout to Git#

When Configuration Is Applied#

Manual Configuration Customization#

Editing .gitattributes#

Editing .gitignore#

Relationship Between spec.yaml and Manual Edits#

When to Modify spec.yaml vs Configuration Files#

Related Topics#