Git in AI Workbench#
Overview of Git in Workbench#
Git versioning is a core feature of Workbench and an important part of keeping things organized, portable and reproducible.
What is it?#
You can manage project versioning with the Desktop App, the Workbench CLI, or any other Git client
The Desktop App has basic Git operations like commit, merge and branch
You can see file changes (from previous commit) as well as local repository status vs a remote
Direct Git support in Workbench is supposed to be an “easy button”.
It doesn’t support all Git operations, for example
git rebaseHowever, you can use Git in the terminal or any other Git client without any issues
How does it work?#
Clone or create a project in the Desktop App
Make changes to the project and review changes in the Desktop App
Do Git operations in the Desktop App, the terminal or any other Git client
Commit changes to the project
Push changes to a remote repository
Note
The best way to understand how Git works in AI Workbench is to work through the exercises in the Onboarding Project.
Basic Git Usage in Workbench#
Git in the Desktop App is an “easy button” for simple Git operations. It does something quickly and easily, but it is not a full-featured Git client.
Git operations initiated by Workbench (and not the Git client in the terminal) are handled with Workbench affordances, e.g. automated commit message
Git operations initiated outside of Workbench, e.g. in the terminal, are done as usual without any Workbench affordances
You can generally move back and forth between the Git operations via Workbench and via another Git client without any issues
However there are some limitations, and if you need to do more complex things than simple branching, merging and commits, you should do them entirely in the terminal or any other Git client
Cloning or Creating a Project#
These must be done in the Desktop App (or Workbench CLI) to create project-specific metadata
If you do an ordinary Git clone or Git init, it will not register the project with Workbench
Workbench requires additional metadata that ordinary Git does not create
For example, creating or cloning with Workbench adds an entry to the
$HOME/.nvwb/inventory.jsonfile and creates a project runtime metadata folder
File Tracking#
Workbench calls Git under the hood to monitor and version files
The Desktop App shows live Git status and file changes with respect to the previous commit
You can discard changes or add to git-ignore on a file by file basis from the Desktop App
Commits and History#
You can make commits in the terminal with Git, through VS Code, or with the Desktop App
Commits made in Workbench or another Git client go to the same Git history
Workbench automatically generates an editable commit message listing the changed files
You can see the commit history in the Desktop App
Workbench uses your global Git author settings for commits for all projects on all locations
Branching and Merging#
You can create, switch, and merge branches in the terminal with Git, through VS Code or with the Desktop App
Merging conflicting branches in the Desktop App prompts you to resolve conflicts
Workbench gives you resolution like choosing between My changes or Their changes, or by directly editing the conflicted files in VS Code or your default editor
You can abort a merge request
Fetch, Pull, and Push#
Once a project is cloned or created, you can fetch, pull and push from any other Git client
If there are conflicts on pull, Workbench will prompt you to resolve them
Deleting Local Branches#
Deleting local branches in the Desktop App has some guardrails
It requires the branch to be at a commit and the remote repository to be up to date
Any uncommitted changes or not being pushed to the remote blocks deletion in the Desktop App
However, you can delete a local branch (without committing or pushing) manually with Git:
git branch -D <branch-name>
Git LFS#
AI Workbench uses Git Large File Storage (LFS) to efficiently manage large and binary files.
For new projects created in AI Workbench, certain directories are automatically configured to track files with Git LFS. These directories include data/ and models/. For more information, see Default AI Workbench Project Structure.
Important
Depending on your Git server, Git LFS may have usage limits and associated fees. Be sure to check your provider’s policies for details.
Limitations of Git in Workbench#
You cannot use the Desktop App for all of your Git operations because it isn’t built for that
For example, you cannot rebase, cherry-pick, or interactively edit the Git history in the Desktop App
However, you can do Git as usual outside of the Desktop App without any issues, except for clone and init
There are cases where trying to mix Git operations in the Desktop App and outside of it will cause issues
For example, rebasing with conflicts is best done entirely outside of the Desktop App, although the results will be reflected in the Desktop App
Making Selective Commits#
The Desktop App treats all files as if they are effectively staged, and any changes not discarded or ignored will be included in the commit
This can be inconvenient if you want to keep some dirty files in the working directory while commiting some
You should make selective commits outside of the Desktop App
The commits will be reflected in the Desktop App and the dirty files will still be show as such in the changes page
Creating a branch at a specific commit#
The Desktop App only lets you create a branch from the current commit
This is inconvenient if you want to create a branch at a previous commit
You should make such a branch outside of the Desktop App
The new branch will be reflected in the Desktop App
Rebasing#
You should do all aspects of rebasing from another Git client or from the terminal
Rebasing with conflicts will trigger merge resolution flows in the Desktop App, which should be ignored because it won’t work properly
The new branch will be reflected in the Desktop App
FAQs#
How am I supposed to do manual Git on a remote project repository?#
This is a great question, and there are a few ways to do it.
Git is installed in the project container, and all of your Git configuration is passed there.
Open JupyterLab in the project container and use Git in the terminal there
Use Git versioninig in VS Code if you’ve added it to the project
Hint
You can also use the Workbench CLI to attach your local terminal to the remote project container and use Git there.
Run nvwb attach -h to see how.
Why can’t I clone a project using standard git clone?#
AI Workbench requires creation and tracking of project-specific metadata during cloning, which standard Git clone does not capture.
For example, Workbench creates an entry for the project in $HOME/.nvwb/inventory.json, as well as information about the container build
and other environment metadata for the project. That information goes into the folder HOME/.nvwb/project-runtime-info/<project-name>-<hash>/.
This metadata is required for Workbench to properly manage the project and provide various features.
Why can’t I clone a regular Git repository with Workbench?#
AI Workbench requires specific files and folders within the repository, such as .project/spec.yaml to provide the various features.
Repositories that include required files are recognized as AI Workbench projects (AI Workbench Projects).
If you try to clone a Git repository in Workbench that doesn’t have the required files, Workbench will not be able to recognize it as a project and will return an error.
However, you can make any repository compatible by adding the necessary files and folders. For details on structuring repositories for AI Workbench, see Default AI Workbench Project Structure.