User Guide Getting Started Help Center Documentation Community Training
Looker
Using Version Control and Deploying

Looker provides a Development Mode to let you develop your model in a safe environment that will not impact other users—until you are ready to deploy your changes.

This page assumes that your project has already been set up for version control. If you see a Configure Git button instead of the choices described on this page, you need to first set up Git for your project.

Git Integration for Version Control

Looker uses Git to record changes and manage file versions. Each LookML project corresponds with a Git repository, and each developer branch correlates to a Git branch. Git repositories are often called “repos”.

Looker generally uses GitHub for LookML source file management. However Looker also can be configured to work with other Git providers such as GitLab, Bitbucket, or any Git server that can use an SSH key for authentication.

A Looker project uses only one account with your Git provider for all Git interactions (see this page for information on setting up Git). For each Looker project, all of the development from all of your Looker developers goes through this one Git account. This means that Looker developers do not need to have their own accounts with your Git provider, unless your Looker instance is set up with one of the additional Git integration options. In this case, a developer would need a Git account to open external links to your Git provider or to create a pull request.

Working with Git Branches

One of the main benefits of Git is that a developer can work in a branch, an isolated version of a file repository. You can develop and test without affecting other users. As a developer in Looker, you are using a Git branch whenever you are in Development Mode.

Another major feature of Git is the ease of collaborating with other developers. You can create a branch and possibly make changes, then other developers can switch to that branch to review or make changes to the branch. If another developer has committed changes to the branch, Looker displays the Pull Remote Changes button. You should pull those committed changes to the branch before making additional changes.

Personal Branches

The first time you go into Development Mode, Looker automatically creates your personal Git branch. Your personal branch starts with "dev-" and includes your name:

Your personal branch is specific to you, and cannot be deleted. In addition, your personal branch is read-only to all other developers. Keep this in mind if you are collaborating with other developers on a project. Instead of using your personal branch to work on the project, you may want to create a new branch so that others can switch to the branch and contribute changes as well.

TIP: You can’t make changes to another developer’s personal branch. So if you want to build on work in somebody’s personal branch, create a new branch starting from their branch.

Creating a New Git Branch

If you are working on a simple fix and not collaborating with other developers, your personal branch is usually a good place to work. You can use your personal branch to make quick updates, then commit the changes and push them to production.

However, you may also want to create new Git branches in addition to your personal branch. A new Git branch makes sense in these situations:

If you have a merge conflict on your current branch, you must resolve the conflict before you can create a new branch.

Also, if you want to create a new branch but have uncommitted changes on your current branch, decide whether those changes should be part of the current branch or the new one. If you want the changes to stay on your current branch, commit the changes before creating a new branch. Otherwise, you can leave the changes uncommitted, create a new branch, then commit the changes in the new branch.

To create a new Git branch:

  1. Verify that you have Development Mode turned on.
  2. Navigate to your project in the Develop menu.
  3. Typically you’ll want to start from the production branch for your new branch. If instead you want to start from an existing development branch, you’ll need to ensure that you have a copy of all committed changes to that branch. To do this, sync your local version of the existing branch with the remote version on your Git server:
    1. Switch to that development branch.
    2. Click the Pull Remote Changes option to sync your local version of that branch.
  4. In the project, select New Branch from the Git drop-down menu. This opens the New Branch window.
  5. In the New Branch window, enter a name for your branch. Note that there are limitations for Git branch names, see this section for naming requirements.
  6. Click the Create From drop-down menu and select an existing branch to use as the starting point for your new branch.
  7. Click Create to create your branch.

Rules for Naming a Git Branch

Looker uses the branch naming convention requirements specified by Git.

Git branch names must not:

In addition, the branch name can only contain an asterisk (“*”) if the asterisk represents an entire path component (e.g., “foo/*” or “bar/*/baz”), in which case it is interpreted as a wildcard and not as part of the actual branch name.

Switching to Another Git Branch

If you have a merge conflict on your current branch, you must resolve the conflict before you can switch to a different branch.

Also, if you have uncommitted changes on your current branch, you cannot switch to an existing branch. You can, however, create a new branch from your current branch. When you create a new branch, any uncommitted changes will follow you so you can commit the changes in the new branch.

To switch to a different Git branch:

  1. In the project, select Switch Branches from the Git drop-down menu to open the Switch Branch window.
  2. In the Switch Branch window, click the Switch To drop-down menu to select the branch you want to switch to.
  3. Click Switch to switch to the branch.

Managing Git Branches

The Branch Management tab of the Project Settings page shows a table of all the Git branches for the Looker project. To open the Branch Management tab, select Manage Branches from the Git menu:

The branch table provides the following information about each branch:

Is your master branch many commits behind? Click here to see why 

The first time you go into Development Mode, Looker syncs your local version of master to the remote version of master. This is the only time that Looker syncs the local and remote versions of master. At that point, the Branch Management tab will show the master branch as being up to date. But from then on, as developers make commits and push their changes to the remote master branch, you will see your local version of the master branch become more and more behind the remote version. But not to worry—Looker doesn’t use your local version of master. Instead, Looker uses the remote master for creating new Git branches. Using the remote version of master ensures that new branches are based on the latest version of master.

Deleting Git Branches

From the Branch Management tab you can delete branches that have a Delete button in the table. You cannot delete the following branches:

In the table, these branches don’t have a Delete button. Instead, the Action column of the table shows the reason that the branch can’t be deleted.

You cannot restore a branch once it’s deleted. When you delete a branch, Looker removes your local version of the branch and the remote version of the branch.

However, if the branch was created by another developer, or if other developers have checked out the branch, those developers will still have their local version of the branch. If a developer makes commits to their local version of the branch and pushes it to production, you will once again see a remote version of the branch. This may be handy if you do want to restore the branch. Otherwise, when you delete a branch, all other developers should delete the same branch to ensure it can’t be accidentally resurfaced by someone pushing it to remote.

To delete one or several Git branches from your project:

  1. From the project, select Manage Branches from the Git drop-down menu.
  2. Use the checkboxes to select one or more branches, then click Delete Selected Branches.
  3. Alternatively, use a branch’s Delete button to delete that one branch.

Executing Git Commands in Looker

Looker has a built-in interface that integrates with your Git service. In the LookML IDE, you’ll see a button in the upper left for Git:

The Git button shows different options, depending on where you are in the process of making changes and deploying to your Production Mode. In general, the option shown on the button is the best guide for your next action.

The Git button also has a drop-down menu, from which you can execute additional commands. (The commands available on the drop-down menu depend on where you are in the process of making changes and deploying to your Production Mode.) For example:

If your developer branch is in sync with the production branch, you will see the Up-to-Date with Production message instead of a Git button. In this case, you can still use the Git drop-down menu:

Finally, experienced Git users can access additional options for the Git menu by holding down the shift button while clicking the Git menu:

Getting Your Changes to Production

To give business users access to your changes, you need to commit the changes and then deploy to production. Before committing, you may want to first review the uncommitted changes.

If you see a Configure Git button instead of the choices described in this section, you need to first set up Git for your project.

Viewing Uncommitted Changes

Once you have saved changes to your files, you can review all of your changes before committing them by using the View Uncommitted Changes option from the Git drop-down menu:

In the Uncommitted Changes to Project window, you can see a summary of all of the uncommitted, saved changes in all of the project’s files. For each change, Looker shows the following:

The LookML IDE also has several indicators are always displayed when you are in Development Mode and have uncommitted changes, as described on this page.

Committing Changes

After you have made and saved any changes to your LookML project, the IDE may require you to validate your LookML:

Whether or not this is required depends on your project’s setting for code quality. For more information on the Content Validator, see this documentation page.

Once you save your changes (and fix any LookML warnings or errors, if required by your project’s code quality setting), the Git button displays the following message:

If desired, you can first review your uncommitted changes before committing.

When you are ready to commit the changes, use the Commit Changes button to commit these changes to your current branch. The following window displays, listing the files that have been added, changed, or deleted.

Enter a message that briefly describes your changes and uncheck any files you don’t want included in the sync. Then click Commit to commit the changes.

Deploying to Production

If you want to push your committed changes to the Production Mode so that other users can see them, click Deploy to Production.

If your project is configured for Git integration using pull requests, you will see the Open Pull Request button instead of the Deploy to Production button. The Open Pull Request button opens a new browser tab directly to the new pull request page on your Git provider’s website, and automatically fills in the title with the developer’s commit message from Looker

Checking the Impact of Your Changes

After making your changes available to the organization you can use content validation check to make sure you have not invalidated any dashboards or saved Looks. You’ll have the opportunity to fix them if you have.

Handling Typical Issues

While working on your model, you may need to:

Some changes, such as changing the name of a field, can affect existing dashboards and Looks. As mentioned earlier, after making your changes available to the organization you can use content validation to check your content and fix any issues.

Reverting Uncommitted Changes

If you do not want to deploy your saved changes, you can revert all of the uncommitted changes for all files in the project or just text changes in a single file.

To revert uncommitted changes for all files, use the Revert Uncommitted Changes option from the Git menu:

To undo the deletion or renaming of a file, you must use this Revert Uncommitted Changes option to revert all uncommitted changes.

To revert any additions or deletions in the contents of a single file, select the Revert Changes option from the file’s gear menu:

Resolving Merge Conflicts

Typically Git can automatically merge your new changes with the production version of your LookML files. A merge conflict occurs when Git has trouble determining which changes to keep. This usually occurs when another developer has made changes since you last pulled and you made changes in the same area. If you have a merge conflict in your code, you will be warned in Looker after you commit changes and pull from production:

When Looker shows the merge conflict warning, it is crucial that you do not push any further changes until you have resolved the merge conflict. Pushing a merge conflict to production will cause parse errors that may prevent exploration of your data.

In the LookML file itself, the lines with conflicts are marked like this:

<<<<<<< HEAD
your code
=======
production code
>>>>>>> branch 'master'

Looker shows the following merge markers to indicate the merge conflicts:

In the example above, "your code" represents the changes you committed, and "production code" represents the code that Git could not automatically merge your changes into.

To resolve a merge conflict:

  1. Find the files with merge conflicts. Looker marks these files with a red exclamation symbol, or you can also search your project for merge markers, such as <<<< or HEAD, to find all of the conflicts in your project.
  2. In the file, go to the lines with merge conflicts.

  1. Delete the version of the text that you do NOT want to keep, and also delete all of the merge markers.
  2. Save the file, and repeat the above steps for any other files marked with merge conflicts.

TIP: Search your project for each of the merge markers to verify that you have resolved all conflicts and deleted all of the merge markers. Make sure to remove all instances of merge markers in your LookML files. These markers will cause parse errors that can prevent users from exploring your data.

  1. After you have resolved all merge conflicts and deleted all merge markers from your project, click on Commit & Resolve Conflict to commit your changes.
  2. Enter a commit message to describe your changes.
  3. Click Commit to commit your merge conflict resolution.
  4. Click Deploy to Production to push all of your changes to production.

Now that you have resolved the merge conflict and pushed your resolution to production, other developers can pull from production and continue work as usual.

Git Garbage Collection

Git garbage collection cleans up unnecessary files and compresses file revisions to optimize your Git repository. Git garbage collection (git gc) is run automatically when your Looker instance is upgraded or rebooted. To keep from running git gc too often, Looker waits 30 days since the last git gc, then runs git gc on the next reboot.

In rare cases, you might try to Push Changes to Remote or Push Branch to Remote while git gc is running. If Looker displays an error, wait for a minute or two and then try again to push your changes.

All Available Git Commands

This table describes all of the Git commands and shows the ways you can access each command:

Function Description How to Access
Configure Git If you have just created a project, you will need to configure Git for the project. See this page for information on connecting a Looker project to a Git repository. Button
Test Git Connection ADDED4.20 Once you have configured Git for your project, you can use the Test Git Connection option to run the Git Test Connection tool to verify that the Git connection is set up properly. See this page. Button,
Shift-click Git menu
Validate LookML If you have saved changes to your files, you may see the Validate LookML button. (Whether or not you are required to validate your LookML depends on your project’s setting for code quality.) Click the button to start LookML validation of your model. See this documentation page for more information. Button
View Uncommitted Changes If you have saved changes that you have not yet committed, you can use the View Uncommitted Changes option to see all of the changes that you have saved since your last commit. See this section for more information. Regular Git menu,
Shift-click Git menu
Revert Uncommitted Changes If you have saved changes that you have not yet committed, you can use the Revert Uncommitted Changes option to discard all of the changes that have not been committed. See this section for more information. Regular Git menu,
Shift-click Git menu
Revert to Production The Revert to Production option is supported only for a user’s personal branch (that is automatically created and begins with dev-). Revert to Production discards any changes in your personal branch and syncs your local files to the current production branch files. Note that this has two effects:
  1. Discards any of your committed and uncommitted changes that have not been deployed to production.
  2. Updates your personal branch with any changes that other users have made to the current production branch.
Regular Git menu,
Shift-click Git menu
Revert to Remote The Revert to Remote option discards any changes in your local branch and syncs your files to the current version of the remote branch. Note that this has two effects:
  1. Discards any of your committed and uncommitted changes that have not been committed and synced to remote.
  2. Updates your local files with any changes that other users have pushed to the branch on the remote end.
Button
Commit Changes After you have made and saved any changes to your LookML project, use the Commit Changes option to commit these changes to your local branch. See this section for more information. Button,
Shift-click Git menu
Deploy to Production After you have committed changes, use the Deploy to Production option to update the production branch with the committed changes from your development branch. Button,
Shift-click Git menu
Push Changes to Remote If you have committed changes to your current branch that are not yet pushed to the remote version of the branch, you will see the Push Changes to Remote button. The Push Changes to Remote operation applies to the branch you’re currently on, pushing all committed changes from your local files and syncing them to the remote end. Button
Push Branch to Remote If you have created a branch that does not exist on the remote end, you will see the Push Branch to Remote button. The Push Branch to Remote option creates the branch on the remote end, pushing all committed changes from your local files to the remote end. Note that this does not deploy your changes to the production branch. Button
Pull Remote Changes If other people have committed and pushed changes on a branch, the remote version of the branch will be ahead of your local version of the branch. The Pull Remote Changes option applies to the branch you’re currently on, retrieving the most recent versions of any changed files on the branch from the remote end and syncing them to your local files. Button
History Click the History menu option to see a list of the commits to your development branch, which includes all of the commits that you have pulled into your development branch from the production branch (including commits from other users).

If you are using GitHub and the Git Project Settings has GitHub Integration enabled, each of the commits will include a link to the commit on GitHub so you can view the exact changes. This functionality also works with other Git providers if your Git Project Settings has that Git provider’s equivalent to GitHub Integration enabled. To open the links, you will need an account on your Git provider.
Regular Git menu,
Shift-click Git menu
Project Settings Opens the Project Settings window, where you can reset the Git provider connection and configure such settings as the project name, LookML validation requirements, and integration with the Git provider. Regular Git menu,
Shift-click Git menu
Git Branching Functions
(see this section for information on working with Git branches)
New Branch ADDED5.0 Opens the New Branch dialog, where you can create a new development branch off the current branch. See this section for more information. Regular Git menu,
Shift-click Git menu
Switch Branches ADDED5.0 Opens the Switch Branch dialog, where you can select a different development branch to work on. See this section for more information. Regular Git menu,
Shift-click Git menu
Manage Branches ADDED5.12 Opens the Branch Management tab of the Project Settings page, where you can see all the Git branches for your Looker project. You can also delete a branch, unless the branch is the production branch, the master branch, the branch you’re currently on, or a developer’s personal branch. Regular Git menu,
Shift-click Git menu
For Projects Where Pull Requests are Recommended or Required
Open Pull Request The Open Pull Request option will open a new browser window to your Git provider’s new pull request page. From there you can create a pull request for your developer branch.
NOTE: Until the pull request is approved and/or closed, all future commits on the branch will be included in the same pull request.
Button
Open Pull Request on GitHub The Open Pull Request on GitHub option will open a new browser window to your Git provider’s new pull request page. From there you can create a pull request for your developer branch.
NOTE: Until the pull request is approved and/or closed, all future commits on the branch will be included in the same pull request.
Shift-click Git menu
Open Project on GitHub The Open Project on GitHub option opens a browser window to the GitHub project files. Shift-click Git menu
For Advanced Git Users Only
Pull from Production The Pull from Production option will pull the current state of the remote production branch and merge it into your local developer branch, and then push the current local developer branch to the remote developer branch. Button,
Regular Git menu,
Shift-click Git menu
Pull Remote Changes If other people have committed and pushed changes on a branch, the remote version of the branch will be ahead of your local version of the branch. The Pull Remote Changes option applies to the branch you’re currently on, retrieving the most recent versions of any changed files on the branch from the remote end and syncing them to your local files. Shift-click Git menu
Push Changes to Remote If you have committed changes to your current branch that are not yet pushed to the remote version of the branch, the local version of the branch will be ahead of the remote version of the branch. The Push Changes to Remote option applies to the branch you’re currently on, pushing all committed changes from your local files and syncing them to the remote end. Shift-click Git menu
Top