Submodules & Git LFS

Phogit handles repositories that include other repositories as submodules, and repositories that keep large files in Git LFS (Large File Storage). Both are free.

Submodules

A submodule is a repository of its own inside another one, pinned to a particular commit. The outer repository records which commit; the submodule’s folder holds that commit’s files.

Clone with submodules

Include submodules in the Clone Repository sheet is on to start. After the clone, Phogit fetches every submodule, and any submodules inside those, with the same sign-in, and checks out the commit the repository records for each. The sheet shows the progress.

If fetching a submodule fails, or you tap Stop, the clone is kept and Phogit says what happened. You can fetch the rest later from the Submodules screen.

The Submodules screen

When the open repository has submodules, the sync menu has Submodules…. It lists each submodule with its path, URL, the commit the repository records (Recorded), the commit checked out in its folder, and its state:

State Meaning
Not initialized The submodule hasn’t been fetched; its folder is empty.
Up to date The folder has the recorded commit checked out.
Out of date The folder has a different commit checked out.
Modified Files inside the submodule have been edited.

For each submodule:

  • Initialize fetches a submodule that isn’t initialized yet and checks out the recorded commit.
  • Update checks out the recorded commit, fetching it first if needed. Submodules inside it are updated too.
  • Open as Repository adds it to your repository list, so you can work in it.

The menu at the top right has Update All and Sync URLs, which copies the submodule URLs from .gitmodules into the repository’s settings, for example after a submodule moved to a new address. While Phogit fetches, Stop cancels; submodules fetched so far are kept.

Submodules sign in like the repository itself: with your token for HTTPS URLs, or your SSH keys for SSH URLs.

Submodules in Files

In the file browser, submodule folders have their own icon. Long-press one and choose Open as Repository, or open the folder and tap Open as Repository at the top. A submodule that hasn’t been fetched says so; initialize it from Submodules….

A submodule you open as a repository appears in Repos like any other: you can commit in it, and push it if you have Phogit Pro. Its files belong to the outer repository, so removing it from the list only offers Remove from List.

Submodules in Changes

When a submodule has a different commit checked out than the one the repository records, for example after you committed and pulled inside it, Changes lists it as a changed submodule with both commits. Stage and commit it like a file to record the new commit, or Update it from Submodules… to go back to the recorded one.

A submodule whose only changes are edited files inside it isn’t offered for staging. Commit those changes in the submodule itself (open it as a repository), then come back and record its new commit.

Git LFS

Git LFS keeps large files, such as images, audio, models or datasets, on a separate server, and stores a small pointer file in the repository in their place. Phogit works with LFS as git does on a computer with git lfs installed: you see and edit the real files, and commits hold the pointers.

Downloads

After a clone, pull, checkout, merge or any other change that brings in LFS files, Phogit downloads their content and puts it in place of the pointers. A banner at the bottom of the file browser, Downloading Git LFS files…, shows the progress.

The file browser marks LFS files with a small LFS tag. A download arrow next to it means the file is still a pointer and hasn’t been downloaded.

Phogit signs in to the LFS server as it does to the remote: with your token over HTTPS, or your SSH key over SSH. Content it downloads is checked against the pointer; a file that doesn’t match is thrown away and stays a pointer.

Repository Settings

Choose Repository Settings… in the sync menu. Under Git LFS:

  • Download LFS Files is on to start. Turn it off to keep the small pointer files instead, to save space and data.
  • Git LFS Files and Not Downloaded count the repository’s LFS files.
  • Download Now fetches files that are still pointers.
  • If the last download left files out, the reason is shown here. Phogit doesn’t keep retrying a file that failed until you tap Download Now or something changes.

Commits and pushes

Edit, stage and commit LFS files as usual. In Changes, an LFS file’s diff shows its pointer (the oid and size lines) rather than its content, as git diff does, and LFS images don’t get an image diff.

When you push, Phogit first uploads the new LFS content to the LFS server. If the server refuses an upload, or is missing content that isn’t on your device either, the push stops before anything changes on the remote and says which files.