Using Git with Applications

The Version Control panel is where you do day-to-day Git work in Koodisi: staging and committing changes, switching branches, stashing work in progress, and pushing to and pulling from your remote repository. It integrates Git into the workspace so you can do all of this without the command line.

Before you begin

• The application must be Git-enabled. See Creating a Git-Enabled Application or Add Git to an Existing Application.
• You need Git credentials with access to the repository for any operation that reaches the remote — Pull, Push, and Fetch.

info

When you create a Git repository for your Koodisi applications, do not let the provider add a readme automatically. Koodisi treats a repository with existing history — including a readme-only repository — as content to be cloned rather than initialized. If you already have such a repository, use Clone from Git instead.

Opening the panel

Open your Git-enabled application and select the Version Control icon in the right sidebar. The panel opens with the current branch name at the top, a row of Git controls, and four tabs.

The Version Control icon appears only for a Git-enabled application, and only while an application, folder, workflow, resource, or schema node is selected in the tree. If you have a data table or a registry node selected, the icon is not offered.

Updating your Git credentials

Several people may work on the same application, so each person should switch to their own Git credentials at the start of a session. Commits then carry the right author, and the audit trail stays meaningful.

1. Select the Credentials icon in the Version Control panel header.
2. Update your credential details.
3. Select Save.

For guidance on credentials themselves, see Managing Credentials.

The Git controls

Control	What it does
Pull	Downloads remote changes and integrates them into the branch you have checked out. A badge shows how many commits your branch is behind.
Push	Uploads your local commits to the same branch on the remote. A badge shows how many commits the remote is behind.
Fetch	Retrieves updates from the remote without changing your local branches.
Refresh	Re-reads the local repository so the panel reflects the current state of your changes and branches.
More	Opens a menu containing Stash and Fetch & Prune.

The badges on Pull and Push are the quickest way to tell where you stand: hover Pull to see Head is behind by 2 commits, or Push to see Remote is behind by 1 commit. No badge means the branch is level with the remote.

Fetch and prune

When a pull request is merged, the feature branch is usually deleted in the Git provider. Fetch & Prune fetches the latest state and removes remote-tracking branches that no longer exist, so the Remote list under the Branches tab reflects the branches that are actually still there.

Select More > Fetch & Prune.

The Changes tab

Build your application as usual — adding workflows, schemas, and resources. Every change appears on the Changes tab, which shows a count of staged plus unstaged changes in its label.

Changes are grouped under two headings:

• Changes — modified files that are not yet staged
• Staged Changes — files staged and ready to commit

Staging and committing

1. Select the Changes tab and review what you have modified.

2. Stage your changes. Select the stage icon on an individual file, or use Stage all changes on the Changes group heading. You can also select specific files first and stage only those.

3. Select Commit and Push to commit the staged changes and push them to the checked-out branch in one action.

   To commit without pushing, select the arrow beside the button and select Commit. The menu also names the branch a push would go to, so you can confirm the destination before committing.

4. Review the commit message. Koodisi pre-fills one from the files you staged and the change made to each — Added schema 'Person'., Updated workflow 'PersonIntake'., Deleted resource 'field-map'. Edit it to describe why the change was made, which the generated message cannot know.

5. Select Commit or Commit & Push.

Koodisi confirms with All changes are committed and pushed successfully. If the commit succeeds but the push fails, the message says so specifically — the commit is safe locally and only the push needs retrying.

info

The commit button is unavailable until at least one file is staged.

Validation before a push

Koodisi validates the application's workflow mappings before it pushes. If it finds problems, a Validation issues dialog lists them and reports Errors detected in this workflow. Pushing now will include configuration errors.

• Select Cancel to stop and fix the errors first. Nothing is pushed.
• Select Continue Push to push anyway.

Pushing with known errors is sometimes deliberate — sharing work in progress on a feature branch, for example. Pushing them to a branch someone else will merge is not.

Unstaging and discarding

On the Staged Changes heading, Unstage all changes returns staged files to the unstaged group. On the Changes heading, Discard all changes throws the modifications away.

Discarding asks you to confirm at Discard Changes — Are you sure you wish to discard all changes? Select Discard to proceed.

warning

Discarding is not recoverable. The modifications are gone, not stashed. Use the Stash tab if you might want the work back.

The Branches tab

The Branches tab lists your Local branches and the Remote branches Koodisi knows about. The branch you have checked out is marked, and the active and main branches are sorted to the top. Use Search Branch to filter a long list.

Creating a local branch

Local branches isolate a feature, fix, or experiment from the main codebase. They support parallel development and let work be reviewed through a pull request before it reaches a shared branch.

1. Select the + icon beside the Local heading.
2. If your organization has branch naming patterns enabled, select a Branch Type. The required prefix is applied for you. See Git Branching Policy.
3. Enter a Branch name. Use alphanumeric characters with optional hyphens and slashes — anything else is rejected with Invalid branch name. Please use alphanumeric characters with optional hyphens and slashes.
4. Check Preview to confirm the final branch name, prefix included.
5. Leave Checkout branch selected to switch to the new branch immediately. This also carries your current changes across to the new branch.
6. Select Create.

info

A new branch is based on the branch you currently have checked out. To branch from master, check out master and select Pull first — otherwise the new branch inherits whatever you were last working on.

Checking out a branch

Select a branch to check it out, or right-click it and select Checkout. Koodisi confirms with Successfully checked out to <branch>.

If the current branch has changes you have not committed, Koodisi does not switch. What it offers depends on what you have staged:

• With nothing staged, Unstaged changes found asks you to commit or stash before switching, to prevent merge conflicts, and takes you to the Changes tab.
• With staged changes, Changes not saved offers Stash Changes or Commit Changes with a Message field, so you can deal with the work and switch in one step.

Renaming and deleting branches

Right-click a local branch to rename or delete it.

• Rename Branch renames it in place. Koodisi confirms with Renamed branch: <old> to <new>.
• Delete Branch asks you to confirm at Delete this branch? — Performing this action will delete the branch permanently. Select Delete.

Deleting a local branch does not delete the remote branch. Delete that in your Git provider, then select More > Fetch & Prune.

The Stash tab

A stash is a temporary shelf for your work. It saves your changes without committing them, so you can switch branches or pull without losing anything.

Stash covers uncommitted work only, and it is not a recovery tool. Once work is committed it lives in history, and once it is merged and reverted it lives in the target branch's history. Recover those from the Commits tab and your Git provider instead. See Reviewing Commit History and Handling Merge Conflicts.

info

Stashing works from staged changes, so stage what you want to stash first. New Stash stays unavailable while nothing is staged, with the tooltip No changes to stash.

Creating a stash

1. On the Changes tab, stage the changes you want to stash.
2. Select the Stash tab and select New Stash. You can also select More > Stash from the Git controls, or Stash changes on the Staged Changes heading.
3. Review the stash message. Koodisi pre-fills WIP - <branch> - <date and time>. Replace it with something more descriptive if you will come back to it later.
4. Review the files the stash will contain.
5. Select Stash Changes.

Koodisi confirms with Changes stashed successfully. Your working directory is clean, and you can switch branches safely.

Applying and deleting stashes

Select the options icon beside a stash on the Stash tab:

Action	What it does
Apply	Restores the stashed changes and keeps the stash
Apply and Delete	Restores the stashed changes and removes the stash
Delete	Removes the stash without restoring it, after confirmation at Delete Stash?

Restored changes come back to the staging area, where you can commit or discard them as usual.

A stash without a message is listed as Unnamed stash. When there are none at all, the tab reads No stashes found.

The Commits tab

The Commits tab lists the commit history of the branch you have checked out. See Reviewing Commit History.

Next steps

• Merging and Pull Requests — getting a branch reviewed and merged
• Git Branching Policy — organization naming rules
• Handling Merge Conflicts — recovering when a pull or push conflicts
• Troubleshooting Guide — credential, clone, and datastore errors