Sync a workspace through GitHub

You need a GitHub account. A free one is enough. Start on a Mac: the iPhone can join a workspace on GitHub, but cannot put one there.

1. 1Open the workspace and choose Workspace ▸ Put Workspace on GitHub…. You can also use Share… beside the workspace in Settings ▸ General.
2. 2Click Sign in with GitHub. nokko shows a short code. If this device is already signed in, the sheet goes straight to the repository list.
3. 3Click Open github.com/login/device, type the code on GitHub's page and approve the request. Use Copy Code if you would rather paste it.
4. 4Come back to nokko. The sheet carries on by itself once GitHub answers.
5. 5Under New repository, keep the suggested name or type your own, then click Create Private Repository. To use an empty repository you already have, pick it from the list instead.
6. 6Read the summary and click Upload Workspace. The sheet counts the files as they go.

The sign-in asks GitHub for repository access, because nokko must create and write to a repository. You type your password only on github.com, and the sign-in stays in this Mac's Keychain.

Your folder stays exactly where it is. From now on nokko syncs a couple of seconds after each change, every 20 seconds, and when you press the sync button. A large first upload slows down on purpose after 50 files, to stay inside GitHub's limits.

The repository holds the same folders and files as your workspace, so you can read it on github.com. nokko creates it private: only people you invite can see it. Your .nokko folder stays on the device.

Each changed file is one commit, made by the GitHub account signed in on that device. The message gives the action, the path and the device's name.

Add Client Work/Brand Refresh.md (MacBook Pro)
Update Client Work/Retainer.md (Studio iPhone)
Delete Inbox.md (MacBook Pro)

If you edit a file on github.com, nokko downloads it like any other change. The Activity feed shows those commits with their own first line.

You can keep a workspace in your project's own repository. Pick the repository from the list, and the summary offers a Branch field filled in with pm.

nokko starts that branch with no shared history, so nothing on your default branch is touched. Your code's history never sees a task. Teammates join the same branch.

A repository nokko creates, or any empty one, has nothing to protect, so the workspace sits on its default branch instead.

A branch that already holds files is refused, because uploading never merges into an occupied branch. Name a new branch, or pick an empty one.

On the Mac, picking a public repository stops at a warning. Go Back returns you to the list, and Use the Public Repository Anyway carries on. On iPhone the list only marks it Public, with no warning, so check before you tap.

1. 1Choose Workspace ▸ New Workspace…, select On GitHub and click Sign in with GitHub….
2. 2Sign in with the code, as above. A Mac that already holds a working sign-in skips this.
3. 3Pick the repository. If it has more than one branch, check Branch: nokko picks pm when it exists.
4. 4Give the workspace a Name.
5. 5Under Local copy, click Choose… and pick a folder. nokko makes a folder of the workspace's name inside it.
6. 6Click Download 41 Files. The button shows the real count.

Choose a location if you also open these files in Obsidian. The default is inside nokko's own container folder, which Finder and Obsidian do not show.

A joined workspace must start in an empty folder. If the name is taken, nokko says the folder already holds files. Give it another name, or choose another location.

1. 1Open Settings and tap Join a Workspace…, then GitHub.
2. 2Tap Sign In with GitHub. nokko shows a code.
3. 3Tap Open GitHub, which also copies the code. Paste it on GitHub's page and approve.
4. 4Return to nokko and tap the repository.
5. 5The first time, type a name under Name This iPhone. It appears beside this phone's changes.
6. 6Check the workspace name and tap the Join button.

The iPhone picks the branch for you: pm when it exists, otherwise the default branch. It cannot join a branch with any other name, so keep the name pm if you want the iPhone on a repository that holds code. Each device signs in by itself, so nothing secret is copied from the Mac.

1. 1On a Mac that administers the repository, choose Workspace ▸ Edit GitHub Connection….
2. 2Under People, type their login in GitHub username and click Invite.
3. 3On their Mac, they choose Workspace ▸ New Workspace…, select On GitHub and sign in.
4. 4Your invitation appears at the top of the list. They click Accept, and the repository joins the list.
5. 5They pick it and download, as in Join from another Mac.

The invite field appears only for someone who administers the repository. A teammate starting on iPhone has no Accept button, so they accept the invitation on github.com first.

To show a teammate's name instead of their GitHub login, add it to the GitHub field in People & Team.

A delete syncs like any other change, but every version stays in the repository's history. The file also goes to the Trash on each Mac that had it, so look there first: putting it back makes it a new file, and it syncs again.

If the Trash is empty, use the history on github.com:

1. 1Open the repository and switch to the workspace's branch.
2. 2Open the commit history and find the commit named Delete with your file's path.
3. 3Open the commit before it, and copy the file's text.
4. 4Save that text in your workspace folder, at the same path and name.

nokko uploads it on the next pass. On a Mac, Restore a File from a Snapshot… also brings back the Markdown from the last 14 daily copies.

• Sign out on the Mac: choose Workspace ▸ Edit GitHub Connection… and click Sign Out. The sign-in leaves the Keychain and sync pauses until you sign in again. Sign In Again is beside it.
• Sign out on iPhone: open Settings and tap Sign Out of GitHub under Accounts. The files stay, and the workspace stops syncing until you sign in.
• Stop syncing one workspace on the Mac: open that workspace first. Then in Settings ▸ General, open the menu beside it and choose Forget GitHub Connection…. The folder stays as a normal workspace and the repository is not touched. Your sign-in is kept.
• Stop syncing on iPhone: open Settings and tap Stop Sharing on This iPhone. The files stay on the phone.

An organisation's repositories appear only once the organisation has granted nokko access. Until then the list can look empty or incomplete.

1. 1In the repository list, click Missing an organization or repository? Review Nokko's access on GitHub….
2. 2On GitHub's page, find the organisation. Grant access, or request it if you are not an owner.
3. 3If you requested it, ask an owner of the organisation to approve it.
4. 4Close the sheet in nokko and open it again, so the list reloads.

If the list is empty the link is not there. Open github.com/settings/applications, choose nokko under Authorized OAuth Apps, and grant access from that page.

The link is on the Mac only. On iPhone, do this once on a Mac or on github.com, then open the GitHub join screen again.