Version control your code

This document shows you how to use version control in Dataform to keep track of development.

Dataform uses Git to keep track of each change made to the files inside a repository.

In a Dataform repository, you interact directly with the Git repository.

In a connected repository, you interact with the tracking branch of the remote repository that you configured during connecting the repository.

Dataform displays version control options based on the status of changes in your development workspace. For example, Dataform displays the commit option only when there are uncommitted local changes in your workspace. When the files in your workspace are an exact copy of your default or tracking branch, Dataform displays the Workspace is up to date status.

Dataform displays the following version control options:

Commit X change(s)
Commit the X number of local changes in your workspace or selected changed files. Dataform displays the uncommitted changes.
Push to default branch
Push your committed changes to your default branch. This option is available in a Dataform repository if you have no uncommitted changes in your workspace.
Push to your-branch-name
Push your committed changes to your-branch-name. This option is available in a repository connected to a third-party Git repository if you have no uncommitted changes in your workspace.
Pull from default branch
Update your workspaces with recent changes from your default branch. This option is available in a Dataform repository if you have no uncommitted or unpushed committed changes in your workspace.
Pull from your-branch-name
Update your workspace with recent changes from your-branch-name. This option is available in a repository connected to a third-party Git repository if you have no uncommitted or unpushed committed changes in your workspace.
Revert to last commit
Restore the files in your workspace to their state from your last commit.

Before you begin

  1. Select or Create a repository.
  2. Optional: Connect your repository to a third-party Git repository.
  3. Select or Create a development workspace.

Required roles

To get the permissions that you need to use version control in Dataform, ask your administrator to grant you the Dataform Editor (roles/dataform.editor) IAM role on workspaces. For more information about granting roles, see Manage access.

You might also be able to get the required permissions through custom roles or other predefined roles.

Pull changes

If your development workspace is out of sync with your repository, Dataform displays the Pull option. To pull changes from your repository to your development workspace, follow these steps:

  1. On the Dataform page, select a repository.
  2. In the Development workspaces tab, select a development workspace.
  3. On the development workspace page, do the following:
    1. If you are in a Dataform repository, click Pull from default branch.
    2. If you are in a repository connected to a third-party Git repository, click Pull from your-branch-name.

Commit changes

After you make a change in a development workspace, Dataform displays the Commit option. You can commit all local changes or selected files.

In the New commit dialog, Dataform displays the uncommitted changes.

To commit changes from your development workspace to your repository, follow these steps:

  1. On the Dataform page, select a repository.
  2. On the repository page, select a development workspace.
  3. On the development workspace page, click Commit.

  4. In the New commit pane, do the following:

    1. In the Add a commit message field, enter a description for your commit.

    2. Select the changed files that you want to commit.

      If you don't select any files, Dataform commits all local changes. You can filter changed files by file state, filename, and path.

    3. Click Commit All changes, or Commit X changes.

      The button name depends on your selection of files to commit.

Push changes

Dataform displays the Push option after you commit changes. To push changes from your development workspace to your repository, follow these steps:

  1. On the Dataform page, select a repository.
  2. On the repository page, select a development workspace.
  3. Commit changes.
  4. On the development workspace page, do the following:
    1. If you are in a Dataform repository, click Push to default branch.
    2. If you are in a repository connected to a third-party Git repository, click Push to your-branch-name.

Revert uncommitted changes

To revert uncommitted changes, follow these steps:

  1. On the Dataform page, select a repository.
  2. On the repository page, select a development workspace.
  3. Above the Files pane, click the More menu, and then select Revert to last commit.

Resolve merge conflicts

A merge conflict can happen when a local change in your development workspace is incompatible with a change that has been made to the default tracking branch of your repository. Merge conflicts usually occur when multiple users simultaneously edit the same file.

You encounter a merge conflict usually when you pull from a branch after a different user has pushed a conflicting change to the same branch. You need to resolve a merge conflict manually by editing the affected file.

The following code sample shows a merge conflict displayed in a SQLX file:

    <<<<<<< HEAD
    SELECT 1 as CustomerOrders
    =======
    SELECT 1 as Orders
    >>>>>>> refs/heads/main

To resolve a merge conflict, follow these steps:

  1. In your development workspace, in the Files pane, select an affected file.
  2. Edit the file with your chosen changes.
  3. Commit changes.
  4. Optional: Push changes.

What's next