dolt-checkout

Switch to a branch

$ dolt checkout [branch_name]

$ dolt checkout [table]

$ dolt checkout -b [branch_name]

$ dolt checkout -b [branch_name] [commit]

dolt checkout [<branch> | <commit>]
dolt checkout -b <new_branch> [<start_point>]
dolt checkout --ours | --theirs <pathspec>...
dolt checkout [--] <pathspec>...

<branch> | <commit>
    Switches the working database and its schema to the state of the specified <branch> or <commit>. This updates the tables on disk.

-b <new_branch>
    Creates a new branch named <new_branch> and immediately switches to it. This is a convenience shortcut for dolt branch followed by dolt checkout.

<start_point>
    Used with -b, specifies the branch or commit from which the new branch should be created. If omitted, the new branch starts from the current HEAD (the commit the current branch points to).

--ours
    When resolving merge conflicts, this option restores the version of the specified <pathspec> (tables or files) from the current branch's side ("ours").

--theirs
    When resolving merge conflicts, this option restores the version of the specified <pathspec> (tables or files) from the incoming branch's side ("theirs").

<pathspec>...
    Specifies one or more database tables or files (like .doltignore) to be restored. If used without a branch/commit, it restores from the index. If used with a branch/commit, it restores from that specific point in history.

--
    A standard convention to separate options from arguments. Useful if <pathspec> might be mistaken for an option (e.g., if a table name starts with a hyphen).

dolt checkout is a core Dolt command that allows users to navigate through the version history of a Dolt database. It provides functionality to switch to an existing branch or commit, thereby updating the working database tables and schema to reflect that specific point in history. Additionally, it can create and switch to a new branch from a specified starting point. For managing conflicts during a merge, dolt checkout can be used with --ours or --theirs to resolve specific tables or files. It also serves to restore individual tables or files from the Dolt index or a particular commit, effectively discarding uncommitted changes or reverting to a previous state for specific database objects. This command is analogous to the git checkout command, bringing familiar version control operations to structured data.

Unlike Git, which primarily manipulates files, dolt checkout directly modifies the database tables on disk. Uncommitted changes to tables or schema might be overwritten or require staging before switching branches. Dolt provides warnings if a checkout would result in data loss without explicit handling.

A key distinction of dolt checkout is that it physically alters the underlying database files (tables) on disk to reflect the state of the checked-out branch or commit. This is a fundamental operation that makes the database itself version-controlled.

When dolt checkout is used with <pathspec> arguments (e.g., table names), its behavior changes:
• dolt checkout <pathspec>: Restores the specified tables/files from the Dolt index (staged changes) to the working set, effectively discarding local modifications.
• dolt checkout <commit> -- <pathspec>: Restores the specified tables/files to the working set from the state they were in at <commit>.

Dolt was developed by DoltHub with the aim of bringing Git-like version control to SQL databases, addressing the challenges of managing schema and data changes in collaborative database environments. The project began in earnest around 2018. dolt checkout was designed as a direct functional analogue to its Git counterpart, providing a familiar interface for developers to navigate database history, branch, and resolve conflicts, central to Dolt's mission of making databases versionable.

dolt branch, dolt commit, dolt merge, dolt reset, git-checkout(1)