GitSync Wiki

Troubleshooting

Below are some common issues and solutions when using the mobile Git client. This page is not applicable to GitSync Legacy versions (1.712 and lower).

Ongoing Sync Operations

When the app is performing a background sync or other activity, a loading spinner will appear near the top right of the screen. This indicates that the app is operating on your repository.

While an operation is in progress:

  • Most repository actions (such as commits, pulls, or pushes) are temporarily blocked until the operation finishes.
  • The spinner will disappear automatically once complete.

In rare cases, for example, after a force stop or app crash, the spinner may become stuck.
If this happens, you can long-press the spinner to manually reset it.

Only use this reset if you’re sure no sync is actually running.

Resetting the spinner during an active sync can corrupt your repository or cause setup issues.

Concurrent Repository Access

Using multiple Git clients on the same repository at the same time can lead to conflicts or errors such as: the index is locked; this might be due to a concurrent or crashed process.

This typically occurs because GitSync may be syncing automatically in the background while another Git client (for example, Obsidian Git) is also attempting to access or modify the same repository.

The most common scenario is syncing an Obsidian vault while using both GitSync (on mobile) and the Obsidian Git plugin (on desktop).

To fix this issue:

  • Disable the Obsidian Git plugin on your mobile devices where GitSync is installed.
  • To do this, open the Obsidian Git plugin settings on mobile, scroll to the bottom, and enable “Disable on this device.”

This ensures that only one Git client is managing the repository at a time, preventing index lock errors and other concurrency issues.

Blue Commits

If your commits appear blue in the commit list, this usually means they were created with a private GitHub email address that cannot be pushed to your repository.

This occurs when:

  • You have Keep my email addresses private enabled in your GitHub settings.
  • The Author Email field in the app uses your private or masked GitHub email (e.g., 12345678+username@users.noreply.github.com).

When this happens:

  • The commits are created locally and appear blue in the list.
  • The push operation will fail, since GitHub rejects commits made with a hidden email.

The Author Email can be changed in Repository Settings.

To fix this

Disable Keep my email addresses private in your GitHub settings.

or alternatively

  1. Change the Author Email in the app to your correct, public GitHub email.
  2. Back up your locally committed changes (e.g., copy changed files manually).
  3. Perform a Force Pull (see Sync Mode) to remove the incorrect commits from the local history.
  4. Reapply your backed-up changes.
  5. Commit and Sync again. This time, the commits should appear normal and push successfully.

Android Limited Filepath Characters

Android restricts the set of characters that can be used in file and folder names.
This can cause sync or checkout errors if your repository contains files with unsupported characters.

The following characters are not allowed in file or folder names on Android

" * / : < > ? \ |

Solution: Rename the affected files on another device (e.g., desktop) to use allowed characters, then resync the repository.

error reading from the zlib stream

This is a known issue that happens on some Android devices (usually older ones) and means you can’t use the latest versions of GitSync on those devices.

The only solution at the moment is to downgrade to v1.708, which is the legacy version of the app and has better support for older devices, but a more limited featureset, especially compared to the latest versions.

Find out more about GitSync Legacy
Downgrade to v1.708

Enable Open Source App Restricted Settings

Apps installed from outside the Play Store (like the open source APK) are restricted by the Android OS by default.

To allow restricted settings (e.g., accessibility permissions):

  1. Go to Settings > Apps
  2. Tap “See all apps”
  3. Find and select Git Sync
  4. Tap the three-dot menu (•••) > App info
  5. Tap Permissions > Restricted settings
  6. Toggle “Allow restricted settings” to On

If you don’t see “Restricted settings”, your ROM may not support it. Some custom ROMs block this option.
The open source APK does not require Google Play Services and is fully compatible with privacy-focused ROMs.

Git LFS

At this time, the app does not support Git LFS (Large File Storage). See Premium Features for the paid Git LFS option.

To prevent sync issues:

  • LFS-tracked files are automatically added to .git/info/exclude, meaning they won’t sync from the mobile device.
  • These files will still appear in the app under Unsynced Files or Git LFS section for easy reference.

We hope to introduce LFS support soon!

Unsupported Features

Downgrading Android App Version

If you need to revert to a previous version of the GitSync app on your Android device, follow these steps:

  1. Uninstall the Current Version: Go to your device’s Settings, then Apps, locate GitSync, and select Uninstall. Backup your settings before doing this if you’d like.
  2. Download an Older Version: Visit Releases, and search for the version you want to install.
  3. Enable Unknown Sources: If you haven’t done so already, you may need to enable the installation of apps from unknown sources in your device settings.
  4. Install the APK: Once downloaded, tap the APK file in your notifications or file manager to begin installation. Follow the on-screen instructions to complete the setup.
  5. Restore Your Data: If you backed up your data prior to uninstalling, you can restore it in the app.

Downgrading may result in losing new functionalities or bug fixes found in the latest version. Proceed with caution.

Reporting Bugs in the App

You can easily report bugs directly from within the app by using the following steps:

  1. Access Global Settings: Tap the grey gear icon located at the top of the screen to open the global settings menu.
  2. Use the ‘Report a Bug’ Button: Locate and select the “Report a Bug” button within the settings.
  3. Authenticate: You have the option to log in using GitHub OAuth or a GitHub Personal Access Token (PAT).
  4. Describe the Issue: Use the in-app interface to provide details about the issue, including steps to reproduce it.
  5. Submit the Report: Once you submit the report, you will receive a link to the created GitHub issue, allowing you to track the progress and respond to any comments.

Providing thorough details will help me address the issue more effectively.

Sharing Logs by Email in the App

To share logs for troubleshooting, follow these straightforward steps:

  1. Access Global Settings: Open the app’s global settings via the grey gear icon at the top of the screen.
  2. Use the ‘Share Logs’ Button: Select the “Share Logs” option.
  3. Prepare the Email: This action will open your device’s email client with the logs attached in a zip file. The email will also include some basic system information and details about the issue.
  4. Add Relevant Information: Before sending the email, be sure to add specific details, such as the related issue number or additional information about the situation.

Emails without relevant details will be ignored

See also: Authentication Methods, Repository Settings, Merge Conflict Resolution

If you encounter any issues not covered here, please open an issue here

Graph View

Backlinks