Git LFS

You can use the Git LFS tab to manage Git Large File Storage (LFS), which stores large binary files on a separate server.

Navigate the Git LFS tab

To open the Git LFS tab, click Git > Git LFS. The tab belongs to the repository it was opened from, and opening it again brings that tab forward rather than making a second one. To set up LFS in a repository, click the Initialize LFS button.

Every Git tool tab carries a Git tools control beside its title. Use it to move between Git Summary, Remotes, Submodules, Subtrees, Git LFS, Sparse Checkout, Repository Config, and Hooks. The menu marks the tool you are on, and choosing a tool opens it for this repository, or brings its tab forward when it is already open. Each tool is its own tab, so two projects can each have their own.

The Git LFS tab has six sections: Status, Operations, Files, Locks, Tracked Patterns, and Maintenance.

Status

The Status section summarizes. It does not configure anything, and it does not repeat what the sections below already show, so it holds three facts:

Row	Description
Git LFS	The version of the Git LFS program Zide found, or a warning if it is missing or cannot run
Repository setup	Whether this repository is wired up for LFS: `Ready`, or what is wrong
Local storage	Size and object count of the local LFS cache

Each row is one line. A second line appears underneath only when a row needs your attention. Hover a row for supporting detail.

Repository setup covers two things Zide manages for you and you never edit by hand: the filter.lfs.* settings that swap a tracked file’s contents for a pointer when you stage it, and the pre-push hook that uploads objects before a push completes. If either is missing, click Repair LFS Setup. Tracking patterns alone do not mean the repository is set up: without the filters, staging a tracked file stores the whole file instead of a pointer.

Until the setup is repaired, Zide blocks pushes whose LFS content did not upload rather than publishing commits that reference missing objects.

If a pre-push hook already exists but does not call Git LFS, repairing replaces it, and that hook may be running your own checks. Zide asks you to confirm first, and saves a copy of the current hook beside it (pre-push.zide-backup-<timestamp>) before replacing it. The backup path is written to the Console.

Local storage is measured in the background and cached, so opening or refreshing the tab does not wait on it.

Recognize LFS files

The File Browser shows a Git LFS marker in the status area on the right of each LFS file, beside its Git status badge. Staging shows the same marker after the file path. The marker tells you that the file’s contents live on the LFS server and the copy Git tracks is a pointer. The Git LFS icon alone does not show whether the content is downloaded.

In the File Browser, click the marker to open the file’s Details view. This view includes a Git LFS section. A download mark indicates Needs pull. See Git LFS actions and Details view.

If the file on disk is a Git LFS pointer, click Pull File in Preview or Edit to download the content of that file only. The Details view also has Pull File when the content is not in the local LFS cache.

Operations

The Operations section moves LFS objects between your clone and the LFS server.

Operation	Description
Pull	Download LFS content and update working files.
Fetch	Download LFS content to the local cache without changing working files.
Prune	Remove unreferenced local LFS objects

Click Auto-sync LFS objects with pull/push to toggle automatic LFS pull and push with Git operations.

When auto-sync is on, Zide uploads the LFS objects for the branch you are pushing before the Git push runs. If that upload fails, the push stops and the sync controls report Push stopped because Git LFS objects could not be uploaded. The underlying command output is written to the Console so you can see why.

Recover LFS files after a clone

After Zide clones a repository that uses Git LFS, it runs git lfs pull to fetch the real file contents. If Git LFS is missing or the pull fails, the clone still succeeds. Zide reports Clone complete. Git LFS files weren’t downloaded. and writes the reason to the Console.

The repository is on disk and safe, but its LFS-tracked files remain as pointer files. A pointer file is a small text file that stands in for the real content. Install or repair Git LFS, then click Pull in the Git LFS tab to fetch the objects.

Git LFS is an optional dependency, and its pull runs after the repository is already on disk. A failure at that point does not throw the clone away.

Transfer endpoints

Git LFS downloads and uploads through separately configurable endpoints, which can intentionally point at different servers. Because they are configurable, they sit in the Operations section beside the buttons that use them, not in Status.

Two lines show which remote each direction uses, and Configure Sources… opens the settings. Hover a line for the resolved endpoint URL and the configuration key that produced it.

Locking follows the upload remote, because taking a lock is a write.

Download resolves through branch.<name>.remote, then remote.lfsdefault, then origin. Upload resolves through branch.<name>.pushRemote, then remote.lfspushdefault, then remote.pushDefault, then the download chain.

For each direction you can:

Use Git configuration: defer to whatever the repository already has. This is the default, and writes nothing.
Use a specific remote: sets remote.lfsdefault (download) or remote.lfspushdefault (upload).
Use an explicit endpoint: sets lfs.url (download) or lfs.pushurl (upload).

Zide reads and writes Git LFS’s own configuration keys, and never changes per-remote endpoints (remote.<name>.lfsurl, remote.<name>.lfspushurl) that you configured deliberately.

If a remote is bound to a connected account, LFS transfers authenticate with that account, exactly as Git push, pull, and fetch do. The credential is scoped to the endpoint’s host, so a token issued for your code host is never sent to a different LFS server.

Files

The Files section lists LFS files in the current checkout. It starts collapsed. Zide loads the list when you first expand the section.

Each status has its own column. A check mark means the status applies to the file.

Column	Meaning	What to do
Needs pull	The LFS content is not on this computer.	Click Pull in Operations.
Needs push	A local commit uses LFS content that the upload remote does not have.	Push the branch.
Staged	The file has staged changes.	Commit in Staging.
Modified	The file has unstaged changes.	Stage or discard in Staging.

A question mark in Needs pull means Git LFS did not report whether the content is downloaded. Hover it for details.

Needs push compares your commits with the upload remote shown in Operations. Hover the Needs push heading or a check mark in that column to see the remote name.

Navigate from the list:

Click a file name to open the file.
In List, click the folder path under a file name to show the file in the File Browser.
Click a check mark in Staged or Modified to show the file in Staging.
Click a check mark in Needs pull to move to the Pull button.
Right-click a file for Open, Open in New Tab, Show in File Browser, and Show in Staging. Right-click a folder for Show in File Browser.

Use the controls above the list:

Search files filters by path.
Use Show to select All files or filter by a status. Click a status column heading to filter by that status. Click the active heading again to show all files.
Reset filters clears the search and shows all files.
Tree groups files by folder. List shows all files in one list. Zide remembers your choice.

Click Show in Git LFS in a file’s Details view or File Browser menu to open the Files section. Zide expands the folders that contain the file, scrolls to it, and highlights it. Zide keeps your Tree or List choice. If filters hide the file, Zide clears the search and sets Show to All files.

In Tree, folders with only one subfolder and no files share a row, for example design/source/brand. Search and Show expand folders that contain matches. Clearing them restores your previous folder layout.

Click File or Size to sort. In Tree, files sort inside each folder, and folders stay in path order. In List, all files sort together.

The list updates when the index, HEAD, branches, or remote branches change, and after you pull, fetch, track a pattern, or migrate. Click Refresh to reload the list. If the list cannot load, click Retry.

Locks

You can use the Locks section to view files that are locked to prevent merge conflicts.

Each lock shows whether it is yours, someone else’s, or unverified. Force Unlock is available only for a lock the server confirmed belongs to someone else. If the server does not verify lock ownership, Zide will not break the lock, because it cannot tell whose it is.

The file editor’s header also has a lock button. Its tooltip is Lock File when the file is unlocked and Unlock File when the lock is yours. In the File Browser, right-click the file and point to Git LFS to find Lock File, Unlock File, and Force Unlock.

The repository chooses which files offer these controls. If any path is declared lockable in .gitattributes, only files marked lockable offer locking. Declaring that attribute tells Zide which files the project expects people to lock, so Zide follows it as the whole policy. If the repository declares no lockable path, Zide offers locking on files that are Git LFS pointers instead.

When no lock server is configured, the controls stay visible but disabled with No Git LFS lock server is configured for this repository. Zide keeps them visible so you can tell that locking applies to the file but is not set up, rather than not applying to the file.

In the File Browser menu, Lock File is disabled when the file is already locked. Unlock File applies only to a lock that is yours. Force Unlock applies only to a lock the server confirmed belongs to someone else. When the server could not verify ownership, Force Unlock is disabled with Lock ownership could not be verified with the server. This is why Zide refuses to break a lock it cannot attribute.

When locking or unlocking fails, Zide reports Could not lock this file. See the Console for details. or Could not unlock this file. See the Console for details. Zide writes the Git LFS output to the Console.

Click Refresh to refresh the Locks section file list.

Tracked Patterns

You can use the Tracked Patterns section to view file patterns tracked by Git LFS.

Zide evaluates Git’s attribute rules to decide whether a file is tracked, so nested .gitattributes files, overrides such as -filter, character classes, and ** patterns all behave the way Git does.

Click Quick Add to add a file pattern to the .gitattributes file or click Edit .gitattributes to manually add the file pattern.

A warning banner appears if the .gitattributes file has uncommitted changes. Click Open Staging to show the Staging activity.

Track a file from Staging or the file browser

You can add a pattern without opening this tab.

Right-click a file in Staging, or a file or folder in the File Browser.
Select Track with Git LFS… for a file or Track Folder with Git LFS… for a folder. In the File Browser, look in the Git LFS submenu if the file supports locking. Otherwise, the action appears directly in the context menu.
Select a pattern. This file tracks only that file. Same extension tracks every file with that extension in the repository. It appears only when the file name has an extension. A folder has one choice, This folder, which selects every file in the folder, including files added later.
Read the line under Adds to, then select Add Pattern.

Zide writes the pattern to the .gitattributes at the root of the repository that contains the path. For a path in a submodule or a nested repository, that is the inner repository. Zide leaves your uncommitted .gitattributes changes alone.

Zide stages nothing. The result panel tells you what to do next:

Commit .gitattributes with the files that the pattern selects.
If the file is already staged as ordinary content, unstage it, then stage it again. Adding a pattern does not convert content that is already staged.
If Zide cannot read the staged content, unstage the file and stage it again to make sure the pattern applies.
If the file also has unstaged changes, staging it again includes them.

Select Done to close the dialog. After you track a file from the File Browser, you can also select Show in Staging to open Staging. In Staging, the same button refreshes the list.

If a rule already covers the file, the action becomes Open Git LFS in Staging and Show in Git LFS in the File Browser. Its tooltip describes the staged content. For a file in another repository, the File Browser shows Open Git LFS as a disabled action. Open that repository as a project to manage its patterns.

If Git LFS is missing or its setup is incomplete, Zide shows the Git LFS setup card and retries the pattern after you continue.

Maintenance

Click Renormalize Files to re-stage your files through the LFS filters. Use it when files that should be stored as pointers were committed with their full contents, usually because they were added before the tracking pattern existed. Commit .gitattributes first: renormalizing against an uncommitted pattern re-stages files by a rule the repository does not have yet, and the button’s hint says so.

Analyze and migrate history

Choose a History scope, then click Analyze Migration to scan that history for file types that can be moved to LFS.

Scope	What it covers
Current branch	The full reachable history of the checked-out branch. This is the default.
Unpushed commits only	Only commits that are not yet on any remote. This is Git LFS’s own default range.
All local branches	Every local branch. Advanced: more refs are rewritten, and all of them need force-pushing.

Results state the scope they were produced under, and changing the scope clears them.

Migrating rewrites Git history. Zide repeats the effective scope and the affected refs in the confirmation, requires a clean working tree, and refuses to run two migrations in the same repository at once. Git LFS counts untracked files as dirty, so commit, stash, or ignore them first. A long migration can be cancelled from its progress bar. After a migration, the rewritten refs need force-pushing, and anyone else with a clone has to reset to the new history.