Shortcuts & Background Fetch
Phogit can work while you’re not looking at it: its actions in Apple’s Shortcuts app let shortcuts, automations and Siri read and change your repositories, and background fetch checks for new commits and tells you when they arrive.
Shortcuts
Phogit adds these actions to the Shortcuts app. They work on the repositories in Phogit’s list, and every one except Open Repository runs in the background without opening Phogit.
Reading a repository, opening one and cloning are free:
| Action | What it does |
|---|---|
| Get Status | Returns the current branch, how far it is ahead of or behind its remote branch, and the changed, staged, unstaged, untracked and conflicted files. |
| List Repositories | Returns the repositories in Phogit. |
| Get Branches | Returns the local branches, and the remote ones too with Include Remote Branches. |
| Read File | Returns the text of a file, including changes not committed yet. Give its Path inside the repository, such as notes/today.md. Files up to 5 MB. |
| Get Recent Commits | Returns the latest commits on the current branch, newest first (Number of Commits: 1 to 100, 10 to start). |
| Open Repository | Opens the repository in Phogit. |
| Clone Repository | Clones a repository from its HTTPS or SSH URL into Phogit and returns it. |
Actions that change a repository need Phogit Pro:
| Action | What it does |
|---|---|
| Fetch Pro | Downloads new commits without changing your branch, and says how many arrived for the current branch. Leave Remote empty for the current branch’s remote. |
| Pull Pro | Fetches and merges the current branch’s remote branch, as Pull does in the app. |
| Commit Pro | Commits with your Message, as the author in Settings › Git Identity. Include Unstaged Changes (on to start) stages every change first, new files included; turn it off to commit only what’s staged. |
| Push Pro | Pushes the current branch. A branch without an upstream gets one. |
| Stage Files Pro | Stages All Changes, or only the files and folders under Paths. |
| Switch Branch Pro | Checks out a Branch. A remote branch gets a local branch that tracks it. |
| Create Branch Pro | Creates a branch called Name from Start From (a branch, tag or commit; empty for the current commit), and switches to it unless you turn off Switch to It. |
| Write File Pro | Writes Text to the file at Path. Mode is Replace or Append. Creates the file, and its folders, if needed. |
Without Phogit Pro, these actions stop and say so, for example Pushing from Shortcuts needs Phogit Pro., and change nothing. When the shortcut can bring Phogit forward, iOS asks to continue in Phogit, which opens at Phogit Pro.
After an action changes a repository, Phogit shows the change the next time you look at it: in Files and Changes, and in the Files app.
Sign-in and identity
Actions never ask for credentials, because there’s nobody to ask while they run in the background. They use the tokens in Settings › Accounts & Tokens and the keys in Settings › SSH Keys. Public repositories need neither. For a private repository Phogit has no sign-in for, the action fails with a message saying so; Clone Repository offers to finish the clone in Phogit, where you can sign in.
Commit needs your name and email in Settings › Git Identity. If commit signing is on, its commits are signed like the ones you make in the app.
Ask Siri
Siri and Spotlight know some actions without any setup. Say, for example:
- “Get status in Phogit”, or “What changed in phogit-docs in Phogit”
- “Pull in Phogit”, or “Pull phogit-docs in Phogit”
- “Fetch in Phogit”, or “Check for new commits in Phogit”
- “Commit in Phogit” and “Push in Phogit”
- “Show recent commits in Phogit”
- “Open phogit-docs in Phogit”
Use the repository’s name as it appears on the Repos tab. Without a name, Siri asks which repository you mean.
Settings › Shortcuts
Settings › Shortcuts lists every action, under Free and Phogit Pro, with a button that opens Phogit’s actions in the Shortcuts app. Without Phogit Pro, Unlock Phogit Pro is there too.
Build a shortcut
This shortcut adds a line to a notes file and pushes it:
- Open the Shortcuts app and tap +.
- Search for Phogit and add Write File. Choose the Repository, enter a Path such as
notes/inbox.md, and set Mode to Append. For the Text, use Ask Each Time, or a variable from an earlier action. - Add Commit, with a Message such as
Add note. - Add Push.
- Tap ▶︎ to try it.
To run a shortcut on a schedule, for example a Pull every morning, create a personal automation in the Shortcuts app’s Automation tab.
Background fetch Pro
Background fetch checks your repositories’ remotes for new commits from time to time, even while Phogit is closed, and sends a notification when the branch you’re on has new commits.
Turn it on
- Open Settings › Background Fetch and turn on Check for New Commits. The first time, Phogit asks to send you notifications.
- Under Repositories, choose which repositories to check. If none were chosen, turning the feature on chooses all of them. Repositories you add later are off until you turn them on.
You can also turn checking on or off for one repository in Remotes… in the sync menu, with Check for New Commits in the Background.
Use Cellular Data is off to start, so Phogit checks only on Wi-Fi. Turn it on to check on cellular data too.
What happens
- It only fetches. Phogit updates its copy of the remote branches, as Fetch does. It never merges, rebases or changes your files.
- You get a notification when a fetch brings new commits to the branch you’re on, such as main has 3 new commits on origin. There’s one per repository, and a newer one replaces it. Tap it to open the repository.
- You can see when it last ran. The repository list, Settings › Background Fetch and Remotes… show Last checked 5 minutes ago, or why the last check didn’t work, such as The last check was skipped on cellular data.
If notifications are off for Phogit, it still checks, and Settings › Background Fetch says notifications are off.
When it runs
iOS decides when Phogit gets to check, based on how often you use Phogit, the battery and the network. Phogit asks for a check about every 30 minutes at most; it may run less often, or not for a while.
- It doesn’t run while Background App Refresh is off for Phogit; Settings › Background Fetch says so, with an Open Settings button.
- It skips its turn in Low Power Mode, in Low Data Mode, without a network, and on cellular data unless Use Cellular Data is on.
- Each check gets well under a minute. With many repositories, it starts with the ones checked longest ago and picks up the rest next time.
Private repositories
Your tokens and SSH keys can only be read while your iPhone or iPad is unlocked. A check that runs while it’s locked can’t sign in to a private repository, so it fails quietly and tries again next time; Last checked shows why. Public repositories work either way. SSH keys that ask for Face ID or Touch ID, such as Secure Enclave keys, can’t be used in the background.