HomeAboutDownloadDocsContact

Documentation

How to connect an Android folder to a Git repository

Installation

GitSy is available for Android devices running Android 7.0 or later. You can install it from the Google Play Store or download the APK directly.

System Requirements

  • Android 7.0+ (API level 24)
  • 64MB free storage space
  • Internet connection for synchronization
  • Access to a Git repository (GitHub, GitLab, etc.)

Permissions Required

  • Internet: For Git synchronization
  • Folder access: Granted by you through Android's folder picker

Initial Setup

After installing GitSy, you'll need to connect it to your Git repository. This connects one Android folder to one Git repository.

Step 1: Create a Repository

First, create a new repository on your preferred Git hosting service:

💡 Tip

Make your repository private to keep your notes secure. GitSy works with both public and private repositories.

Step 2: Configure GitSy

Open GitSy and follow these steps:

  1. Tap "Add Repository" on the welcome screen
  2. Enter your repository URL
  3. Provide your authentication credentials
  4. Choose an empty local folder through the Android folder picker
  5. Save the project to clone the repository into that folder

Folder Workflow

GitSy does not replace your note editor. Create and edit files with your preferred Android app, then use GitSy to synchronize the folder with the configured repository.

Basic Workflow

  1. Add a repository in GitSy
  2. Select an empty local folder for that project
  3. Edit files in that folder with another app
  4. Return to GitSy and run synchronization
  5. GitSy commits local changes, pulls remote changes, and pushes updates

⚠️ Important

The folder must be empty when connecting a new repository.

Repository Setup

GitSy currently documents HTTPS repository access. GitHub, GitLab, and self-hosted HTTPS Git servers are the primary supported targets.

GitHub

Repository URL format:

https://github.com/username/repository-name.git

GitLab

Repository URL format:

https://gitlab.com/username/repository-name.git

Self-hosted Git

Repository URL format:

https://your-git-server.com/username/repository-name.git

Authentication

GitSy uses username/password-style credentials for HTTPS Git access. For GitHub and GitLab, use a personal access token instead of your account password.

Personal Access Token (Recommended)

The most secure method is using a personal access token:

  1. Go to your Git provider's settings
  2. Generate a new personal access token
  3. Grant repository read/write permissions
  4. Copy the token and paste it in GitSy

🔒 Security Tip

Always use personal access tokens instead of passwords. They're more secure and can be easily revoked if needed.

Synchronization

GitSy synchronizes repositories through a foreground Android service while work is in progress. You can start sync manually for a single project or for all projects.

Available Sync Actions

  • Sync repository: Run sync for one configured project
  • Sync all: Queue all configured projects for sync
  • Periodic check: When the app opens, ready projects older than one hour may be queued for sync

What Sync Does

  • Copies changes from the selected Android folder into the app's Git working copy
  • Commits local changes when present
  • Pulls remote changes from the repository
  • Copies the synchronized result back to the selected Android folder

Project Management

Each project stores a repository URL, credentials, and the Android folder selected for synchronization.

Available Actions

  • Add a repository project
  • Edit repository URL and credentials
  • Delete a project from GitSy
  • Synchronize one project from the context menu

Folder Access

GitSy uses Android's Storage Access Framework. You explicitly grant access to the folder used by each project, and GitSy stores that permission for future sync runs.

Tip

Use an editor that can work with the same Android folder. GitSy handles sync, not editing.

Planned Features

Some features previously described on this site are not part of the current app. They are tracked as future work instead.

  • Markdown preview and editing helpers
  • Search, tags, favorites, and filters
  • Configurable scheduled synchronization
  • OAuth and SSH authentication
  • In-app export and sharing tools

Conflicts

Git conflicts can happen when the same files change locally and remotely. Current conflict handling is based on Git/JGit behavior during synchronization; an interactive conflict review UI is planned but not implemented yet.

How Conflicts Occur

Conflicts happen when:

  • The same note is edited on multiple devices
  • Changes are made while offline
  • Network issues prevent proper synchronization

💡 Best Practice

To minimize conflicts, sync before and after editing the same files on another device.

Backup & Recovery

Each successful sync pushes your folder contents to your Git repository. The repository is the backup and version history mechanism.

Automatic Git Backup

Every time you sync successfully, your files are pushed to your Git repository. This means you have:

  • Complete version history of all changes
  • Multiple copies across all connected devices
  • Recovery from any point in time

You can export or clone the repository with standard Git tooling outside GitSy.

Troubleshooting

Common issues and their solutions to help you get the most out of GitSy.

Sync Issues

Problem: Notes not syncing

Solutions:

  • Check your internet connection
  • Verify repository credentials
  • Try manual sync
  • Restart the app

Problem: Authentication failed

Solutions:

  • Check if your token has expired
  • Verify token permissions
  • Try re-entering credentials
  • Check repository URL format

Problem: App crashes or freezes

Solutions:

  • Update to the latest version
  • Clear app cache
  • Restart your device
  • Check available storage space

Need More Help?

If you're still experiencing issues, please visit our Contact page to get in touch with our support team.