Skip to main content

Working with Git Applications: Best Practices

Most Git problems in Koodisi trace back to a handful of habits. These are the practices worth agreeing as a team, grouped by the problem each one prevents.

Repositories​

Create new applications only in empty repositories. Koodisi initializes a repository when it creates an application there. A repository that already has history — a readme is enough — must be cloned instead, or Koodisi reports Repository already has history, including README-only repositories. Use Clone from Git to preserve it.

Do not let your provider add a readme automatically. It creates exactly the history that blocks initialization.

Know whether your repository is single or multi-module before you create, clone, or delete anything in it. In a multi-module repository, applications share one repository and one branch namespace, so actions on one can affect another. See Single vs. Multi-Module Repositories.

When cloning from a multi-module repository, name the application exactly as its folder is named in the repository. To add another application to the same repository, clone again under the matching name, or create a new multi-module application pointing at the same repository.

Branches​

Protect your main branch and merge through pull requests. With provider-side protection enabled, a direct push is rejected with Pushes to this branch are not permitted; you must use a pull request to update this branch. — which is the protection working.

Check out and pull the intended parent before creating a branch. A new branch inherits whatever you currently have checked out. This is the single most common cause of a branch containing work nobody expected.

Use clear, descriptive application and branch names. Where your organization defines branch naming patterns, create branches from the Branches tab so the prefix is applied for you. See Git Branching Policy.

Delete branches once they are merged, then select More > Fetch & Prune so the Remote list reflects reality.

Committing and pushing​

Commit local changes before pulling. Pulling with uncommitted work is what turns a routine update into a recovery exercise.

Pull remote changes regularly. A branch that has not seen the target branch for weeks accumulates drift, and drift becomes one large conflict.

Push often. LocalDataStore is browser-specific, so an unpushed commit exists on exactly one machine. Pushing to the remote is the only real backup.

Write commit messages that say why. Koodisi pre-fills a message from the files you staged — Updated workflow 'PersonIntake'. — which records what changed but not the reason. Add the reason, particularly if your team squash-merges, where this becomes the one message that survives.

Credentials​

Each developer uses their own credentials. Select the Credentials icon in the Version Control panel at the start of a session. Shared credentials make authorship and the audit trail meaningless.

Prefer saved credentials over entering them per operation, and make sure a new credential has the repository access the work needs.

Schemas and shared artifacts​

Do not delete schemas from Git-enabled applications. Deletion breaks references in Git-enabled and cloned applications. Deprecate the schema, or manage it through the registry.

Merge shared schema and resource changes early. An edited schema becomes branch-scoped, so a branch that edits one diverges from branches still using the reference. Merge the change to the target branch first, then have dependent branches pull. See Schema Guidelines.

Publishing​

Confirm the checked-out branch before you publish. Publishing captures the application as it exists on the branch you have checked out, so publishing from a feature branch publishes that branch's state rather than the merged result your team reviewed.

Publish only from the reviewed target branch, after checking it out and pulling. Where you want this enforced rather than remembered, see Protecting Deployment Branches.

Recovery​

Export the local datastore before any recovery step. Clearing the datastore or re-cloning is not reversible, and an export is the only way back to work that was never pushed. See Managing the Local Datastore.