# Git Integration Objo Studio includes Git support for VCS-friendly `.objosln` solutions. Studio uses its own bundled Git runtime, so you do not need to install Git separately to create a local repository, see changes, commit solution items, or create and switch local branches. Git support is optional. A portable `.objo` solution or a solution outside a Git repository still opens and works normally. Studio can convert the solution and create a repository if you choose to. If the bundled Git runtime is unavailable, source-control commands are unavailable but ordinary Studio work continues. Git features are included free with Studio and do not require a Build, Publish, or Profile licence. Studio intentionally covers a small, safe Git workflow. Use an external Git client for cloning, fetch, pull, push, remote management, authentication, branch tracking, branch rename or deletion, merging, rebasing, conflict resolution, stashing, history, tags, signing-key creation and management, and other advanced operations. ## Prepare a Solution for Git Source-level Git integration is available only for the VCS-friendly `.objosln` format. The portable `.objo` format is a ZIP archive, so Studio does not try to apply Git operations to files inside it. The simplest way to prepare an existing solution is to choose **Source Control > Set Up Git Repository...**. If the solution is portable or has not yet been saved, Studio first opens **Save Solution for Git**, a Save As picker restricted to the VCS-friendly `.objosln` format. In the repository setup dialog: 1. Choose the initial local branch name. `main` is the default. 2. Enter the author name and email for the initial commit. 3. Review or change the initial commit message. 4. Optionally select **Sign the initial commit** to use your existing Git signing key and signing agent. 5. Choose **Create Repository**. The original `.objo` file remains separate. After Save As, continue working with the new `.objosln` solution. See [Objo Solution File Formats](solution-file-format.md#vcs-friendly-package-layout) for its folder layout and ignore rules. Studio creates the repository at the `.objosln` solution-package root. It stores the author name and email in that repository's local Git configuration; these values identify commits and are not remote-host credentials or cryptographic signing keys. The first commit contains only the saved solution manifest and its Studio-owned package files. Local `.objo/` user state and unrelated files are not staged. If the solution is already inside a repository with an unborn branch—one that has no first commit—and an empty index, **Set Up Git Repository...** creates the first commit on that existing branch. It does not replace the branch name. If the solution is inside a repository that already has commits, use **Commit Changes...** instead. Studio does not clone repositories or create one in an arbitrary folder outside the open solution package. ## Repository and Branch Status For an open `.objosln` solution, the status bar shows the local branch and a summary such as `main — Clean` or `feature — Changed (3 items)`. Point to the control for more detail, including: - the repository root and the solution's path inside it - the current branch or detached `HEAD` - upstream and ahead/behind information when available - the bundled Git version - the number of changed logical solution items - the reason branch switching is unavailable, when applicable Choose **Source Control > Refresh Status** to request an immediate refresh. Studio also watches the repository and refreshes after relevant activity. An unborn branch is a branch whose repository does not have a first commit yet. Use **Set Up Git Repository...** to create its initial solution commit. A detached `HEAD` means the repository is checked out at a commit rather than a named local branch. Studio can create a named local branch from that exact commit. ## Change Markers Studio compares the committed `HEAD` version of each source item with the current editor content: - the editor gutter marks added, modified, and deleted lines - the Solution navigator decorates added, modified, deleted, and renamed logical items - the status-bar count reports changed logical items rather than raw package files The comparison includes unsaved editor changes. A source item may use several package files, such as source code, metadata, and a designer layout, but Studio presents them as one logical item. Stable item identities allow markers to follow a source item when it is renamed or moved. Markers require a committed `HEAD` baseline. They are unavailable in a repository with no first commit. ## Commit Selected Studio Changes Choose **Source Control > Commit Changes...** to open the commit dialog. Select one or more logical items, enter a commit message, optionally select **Sign this commit**, and choose **Commit**. Studio groups related package files so a selected item remains internally consistent. For example, a source item's code, metadata, and designer layout are committed together. Project and solution settings, assets, resources, localisation files, renames, and deletions are also represented as logical items. Before committing, Studio: 1. verifies that the solution has not changed externally 2. saves the complete in-memory solution 3. refreshes and revalidates the repository and `HEAD` 4. stages only the exact package paths belonging to the selected logical items 5. runs a normal Git commit, including repository commit hooks 6. refreshes the solution, index, and working-tree status Saving the solution may write unselected changes to disk, but Studio does not stage those paths. Changes outside the solution package are also left unstaged and uncommitted. Studio blocks the commit when the Git index already contains staged changes. Commit or unstage those changes with an external Git client first. It also blocks commits during conflicts, merges or other active Git operations, and while Studio is running another incompatible operation. The dialog does not amend or push the commit, and it does not provide partial-hunk staging. ## Commit Signing Studio can ask its bundled Git client to cryptographically sign initial and ordinary commits. Studio does not create, import, store, or unlock signing keys, and it never collects a key passphrase. Configure the signing key, signing format, signing program, and any required GPG or SSH agent with Git or the platform's signing tools before requesting a signed commit. The signing checkbox initially follows Git's effective `commit.gpgSign` setting for the repository. Selecting it explicitly requests a signed commit; clearing it explicitly requests an unsigned commit. Git chooses the configured key through `user.signingKey` and the configured signing format, such as OpenPGP or SSH. When signing is requested, Studio makes the installed signing tools visible to the bundled Git process while continuing to use Studio's bundled Git executable and helpers. A protected key must be available through a signing agent or a desktop-capable pinentry prompt. If Git cannot create the signature, Studio does not fall back to an unsigned commit. It reports the Git diagnostic and restores the clean or empty index when Git did not create a commit. Studio also checks that a requested signature was embedded in the resulting commit. A Git hosting service shows a signature as verified only when the corresponding public key and identity are registered and trusted there; that hosting-service verification is separate from Studio creating the signature. ## Changes Made Outside Studio Studio checks the solution package against the version it opened or last saved. If a text editor, Git client, branch operation, synchronisation tool, or other process changes a solution-owned file, Studio shows a **Solution changed on disk** banner and disables ordinary Save so the external version cannot be silently overwritten. If Studio has no unsaved changes, choose **Reload**. If Studio also has unsaved changes, choose one of: - **Save As...** to preserve the in-memory work as another solution - **Discard Studio Changes and Reload** to accept the version on disk - **Cancel** to dismiss the banner temporarily while you investigate Dismissing the banner does not accept the changed files or re-enable ordinary Save. You must reload, explicitly discard, or save the in-memory work separately. Reloading preserves surviving open tabs, view modes, selection, and caret positions where possible. It clears stale undo, navigation, diagnostics, compilation, and source-control state because those results belonged to the previous version of the solution. ## Create a Local Branch Choose **Source Control > Create Branch...**, enter a valid local branch name, then choose **Create and Switch**. The branch starts at the current committed `HEAD`, and Studio immediately switches to it. Studio saves current in-memory solution edits before creating the branch. Unstaged and untracked working-tree changes are preserved and follow you onto the new branch. If the solution is nested inside a larger repository, or files outside the solution are changed, the dialog warns that those repository-wide changes also follow the branch. Branch creation is blocked when the index contains staged changes, the repository has conflicts, a merge or another Git operation is in progress, or Studio cannot confirm the current solution and `HEAD`. Commit or unstage index changes before trying again. You can also use this command at a detached `HEAD` to create a named local branch at the current commit. Studio does not create a branch at an arbitrary commit, base it on a remote branch, configure upstream tracking, or rename or delete branches. ## Switch Local Branches Choose **Source Control > Switch Branch...** or select the branch control in the status bar. Studio lists existing local branches and preflights each target before enabling it. Branch switching is available only when: - the solution is a saved `.objosln` package - the current repository is on a named branch with at least one commit - the entire repository is clean, including the index, working tree, and untracked files - no merge, rebase, cherry-pick, revert, bisect, or other Git operation is in progress - Studio has no unsaved or unresolved external solution changes - Studio is not saving, reloading, running, debugging, building, profiling, publishing, committing, or performing another incompatible operation - the selected target is an existing, non-current local branch - the target branch contains exactly one supported `.objosln` manifest in the same solution-package root Switching changes the entire Git working tree, not only the files owned by the open solution. When the solution is nested inside a larger repository, the branch chooser highlights that repository-wide effect before you confirm. Studio does not switch directly to a remote branch or arbitrary commit, force a checkout, discard files, or create a stash. Prepare those workflows in an external Git client. After a successful switch, Studio reloads the target branch's solution and restores workspace state for items whose stable identities still exist. ## Recover from an Interrupted Branch Switch If Git refuses a switch before changing branches, Studio leaves the open solution in place and refreshes the actual repository status. If Git changes branches but Studio cannot load the target solution, Studio attempts to switch back to the exact previous branch only while the repository is still clean. A successful rollback reloads the previous solution. If Studio cannot prove that rollback is safe or successful, it enters recovery-required mode. Editing and Save remain disabled because the in-memory solution may no longer match the checked-out files. Use an external Git client to: 1. inspect the repository root, current branch or `HEAD`, and working-tree status 2. finish or abort any active Git operation 3. restore a clean, named local branch containing a valid `.objosln` package at the expected path 4. return to Studio and reload the solution from disk Do not try to bypass the warning by overwriting the package. Preserve any work you need with the external client before making the repository clean. ## If the Bundled Git Runtime Is Unavailable Studio never silently substitutes a `git` executable from your system `PATH`. If its bundled runtime is missing, damaged, quarantined, or unsupported, the Source Control menu explains that Git is unavailable while the rest of Studio continues to work. Reinstall or repair the same Studio version from an official Objo download. If your operating system quarantined part of the application, follow the normal platform installation and security steps for that signed release rather than copying a different Git executable into the application.