Skip to main content

Troubleshooting & Known Issues


Is my repository initialized for XetHub?

Open your terminal and navigate to the local copy of your Xet repository and check your .gitattributes file. If the first three lines of output matches the following, your repository supports Xet functionality:

$ cat .gitattributes
* filter=xet diff=xet merge=xet -text
*.gitattributes filter=
*.xet/** filter=

I just cloned a Xet repository but my local large files seem to be pointers. What do I do?

The git xet clone command materializes all files by default. If this is not the case, it's possible that the Git-Xet extension was never initialized. Run the following two commands to manually resolve the files:

git xet install
git xet checkout

I'm using Git-Xet for the first time on Windows and a Git for Windows prompt appears. What do I enter?

When connecting with SSH for the first time over Windows, you may encounter the following popup that forgets to ask its intended prompt of: "Do you want to continue? (yes/no)" First Windows SSH

To continue, type "yes" in the box and click OK.

I have to enter my SSH password/passphrase three times each time I push changes! Why is this happening and how do I avoid it?

Behind the scenes, Git-Xet makes multiple requests that can trigger additional password or passcode requests if your local SSH agent isn't configured.

  • To address multiple SSH password requests, add your SSH key to ssh-agent. Follow GitHub's documentation for adding your SSH key to the ssh-agent, making sure to select your OS from the top tabs.
  • To address multiple SSH passphrase requests, configure an authentication agent to securely use your passphrase. Follow GitHub's documentation for working with SSH key passphrases.

How do I update my Git-Xet extension?

Follow our standard installation instructions, which will overwrite the previous installation with the most recent release.

How do I uninstall the Git-Xet extension?

  1. From your terminal, uninstall the extension:

    git xet uninstall
  2. Then delete the pkg file:

    sudo rm /usr/local/bin/git-xet

If you do uninstall the Git-Xet extension, please help us understand what we could've done better!

Known Issues

Mount requirements and limitations

Our mount feature requires NFS client to be installed on the machine or container where it is running. Environments that don't support NFS client (including Google Colab and Windows Home) cannot run mount. If NFS client is not installed, you may see an error message similar to the following:

2023-11-21T19:29:02.226513Z ERROR /root/.cargo/git/checkouts/xet-core-d6815bd7e1c74654/4ba4d13/rust/gitxetcore/src/xetmnt/ Unable to locate /sbin/mount.nfs
2023-11-21T19:29:02.226539Z ERROR /root/.cargo/git/checkouts/xet-core-d6815bd7e1c74654/4ba4d13/rust/gitxetcore/src/xetmnt/ Ubuntu: Install the nfs client package with 'apt install nfs-common'
2023-11-21T19:29:02.226561Z ERROR /root/.cargo/git/checkouts/xet-core-d6815bd7e1c74654/4ba4d13/rust/gitxetcore/src/xetmnt/ Redhat/Fedora: Install the nfs client package with 'yum install nfs-utils'
Error : Unable to locate suitable mount command

Mounting private XetData-enabled GitHub repositories on containers is currently not supported.


  • In environments where you have permissions to install software, you can install the packages necessary to support mount.

    • For Ubuntu (used in the default GitHub Codespaces container):
      sudo apt update
      sudo apt install nfs-common
    • For Redhat/Fedora:
      yum update
      yum install nfs-utils
  • To mount a private repository on a container, host your repository directly on XetHub.

Rendering and file type limitations for automatic differences

UI rendering

Differences between branches can be very large. When displaying differences on XetHub, the following restrictions apply:

  • The UI currently limits the number of files displayed to the first 50 changed files.
  • Text files with over 20000 lines of changes will not be shown on the UI.
  • Text files with line changes of over 5000 characters will only display the first 5000 characters.
  • Differences on files exceeding 8 MiB will not be shown through the UI.
  • Custom visualization differences on files exceeding 8 MiB will not be shown.

Workaround: For any differences exceeding the limits above, mount files or checkout branches locally to review changes. Users also have the option to download before/after versions of each file through XetHub's comparison view UI by clicking the Download button on the right side of each file's Differences header.

Custom visualization limitations

Custom visualizations are fully rendered in the browser and fetch all referenced data on demand. If the referenced data is quite large (beyond perhaps a few hundred MB), it may take a long time to download, and may slow down or even make the page unresponsive.

Workaround: When visualizing large data, consider committing sampled or aggregated data to the repository and referencing that instead.

File type support

XetHub currently supports showing differences on many types of text and image files.

Workaround: For unsupported file types, we recommend mounting or checking out branches locally for a closer look. Expecting difference support on your file type? File an issue to request support for additional file types.

File browser and UI loading limitations

Directories with large numbers of files can slow down the loading of the left pane file browser and main pane file explorer, potentially leading to browser slowness and unresponsiveness.

Workaround: When possible, try to limit the number of files within a single directory. We plan to add a paginated view to improve this experience.

Large pull request limitations

Pull requests are only available through the UI, and may encounter browser timeouts when the number of files changed is large.

Workaround: While we address this limitation, Git push through the CLI works for all size changes. For collaborative review, consider making and pushing changes on a branch, and asking a reviewer to checkout your branch for local review. Once they have approved your change, you can merge your branch to main using the CLI and push your changes.

Account deletion

When users sign up with GitHub, GitLab, or Google, deleting accounts is difficult because there was no password set on account creation.

Workaround: Use the Forgot password? prompt to set your password and then use your newly created password to confirm account deletion.

Windows limitations

  • Mounting repositories on Windows machines requires NFS client, which is unavailable for Windows Home edition. Mount is available for Windows Pro, Enterprise, and Server editions.

  • When first connecting over SSH, you may encounter a Git for Windows popup that warns about the authenticity of Type yes in the text entry and press OK to add XetHub to your known hosts.