Git repositories
Progressive Web Office can open files stored in GitHub (github.com or GitHub Enterprise), GitLab (gitlab.com or self-hosted) and Gitea / Forgejo (Codeberg, self-hosted, on the local network) repositories, and commit your changes back — directly from the browser, without a server of our own. A Git working copy on your own disk works too (see Git on your own computer or network).
Open a repository by its address
The quickest way: paste the address of the repository — the one shown in your browser — in the first field of Open from repository… or Commit…, then press Enter:
https://github.com/s-celles/test-pwo— GitHub, owners-celles, repositorytest-pwo;https://gitlab.com/group/subgroup/project— GitLab, with its groups;- a link to a branch, a folder or a file (
…/tree/dev/docs,…/blob/main/report.md, GitLab…/-/tree/main/docs) opens that branch and that folder, or the file itself; - a clone address (
git@github.com:owner/name.git) or a self-hosted site (https://gitlab.example.org/team/project, GitHub Enterprise) works too.
As soon as the address is pasted, what was understood is shown — GitHub (github.com) · owner s-celles · repository test-pwo — with the branch and the path when the address has them, and the repository opens:
- with your account of that site, if you have one;
- a public repository opens without any token: it can be read and its files opened; saving into it (a commit) needs an account with a token;
- a private repository (or one that does not exist) asks for an account: the form is filled in for that site, only the token is left to paste.
Accounts and tokens
Reading a public repository needs nothing. Everything else needs an account: the site (GitHub or GitLab, public or your own) and a personal access token (PAT) — a password made for applications, that you create on the site, limited to the repositories and rights you choose, and that you can revoke at any time without changing your password.
| What you do | Without a token | With a token |
|---|---|---|
| Open a file of a public repository, browse it as a folder | ✅ | ✅ |
| Open a private repository | ❌ | ✅ (token allowed to read it) |
| Save (commit), create, rename, delete files | ❌ | ✅ (token and role allowed to write) |
| Create a branch, propose a pull / merge request | ❌ | ✅ (pull-request right) |
| See your role and the collaborators | ❌ | ✅ (collaborators: if your role may write) |
Adding an account
There are three ways, all ending in the same form:
- paste the address of a private repository: the form opens, filled in for its site — only the token is left to paste;
- after opening a public repository without a token, 🔑 Add a token to save here; or simply Save: the token is asked then, and checked on the repository before anything is written;
- Add account in the window, for any site.
In the form:
Provider: GitHub or GitLab.
API URL — filled in for the public services; for your own site:
Forge API URL github.com https://api.github.comGitHub Enterprise Server https://github.example.com/api/v3gitlab.com https://gitlab.com/api/v4Self-managed GitLab https://gitlab.example.com/api/v4Personal access token — see below how to create it on each forge.
Remember the token in this browser — ticked by default, so that you do not type it again. Untick it on a shared computer: the token is then kept only until the application is closed (the account shows until closed).
Connect: the token is tried before the account is added.
Forget removes the account and its token from this device.
Several tokens, a token per repository
Add as many accounts as you need, on GitHub, GitLab, Gitea or Forgejo — and several on the same site (GIT-018): a fine-grained token for each repository, a token of a project or of a group, a work account and a personal one. They are listed in Account of the repository window.
When a repository is opened by its address (pasted, a place remembered, a document saved there before), the application takes the account last used for that repository; otherwise it tries the tokens of the site in turn, and takes the one that may write in it, else one that may read it. Which account goes with which repository is remembered in this browser (its name only, never the token).
Creating a personal access token (PAT), forge by forge
How to create a token?, under the token field, repeats the steps for the site chosen, with a link to its token page. Whatever the forge:
- give the token only the repositories and rights you need;
- choose a near expiration date (30 to 90 days) and make a new one when it expires;
- copy it as soon as it is shown — it is shown only once — and paste it in Progressive Web Office; do not keep it elsewhere, never paste it in a document, a message, a chat or a commit;
- if it may have leaked, revoke it on the same page and make another.
GitHub (github.com) — fine-grained token (recommended)
Signed in to GitHub, open github.com/settings/personal-access-tokens/new — or your picture › Settings › Developer settings › Personal access tokens › Fine-grained tokens › Generate new token.
Token name:
PWO(and a description if you like).Resource owner: your account — or the organisation that owns the repositories (see below).
Expiration: 30, 60 or 90 days, or a date.
Repository access: Only select repositories, then pick them. All repositories also works, but gives more than needed; Public repositories is read only.
Permissions › Repository permissions:
Permission Access Needed for Contents Read and write opening and saving files, branches (essential) Metadata Read-only added by GitHub automatically Pull requests Read and write Propose the changes… (optional) Nothing else is needed (no account permission, no administration).
Generate token, then copy it (
github_pat_…).
Repositories of an organisation: choose the organisation as Resource owner. Depending on its policy, the token may wait for an approval by an owner of the organisation (it is then pending: until it is approved, the repositories answer not found), or fine-grained tokens may be refused; ask an owner, or use a classic token if the organisation allows only those.
GitHub — classic token (when fine-grained ones are not possible)
- Open github.com/settings/tokens/new (Personal access tokens › Tokens (classic) › Generate new token (classic)).
- A note (
PWO) and an expiration date. - Scope
repo(private and public repositories) — or onlypublic_repofor public repositories. - Generate token, copy it (
ghp_…).
A classic token reaches every repository you can reach: prefer a fine-grained one. In an organisation with single sign-on (SAML), click Configure SSO next to the token, then Authorize for the organisation.
GitHub Enterprise Server
The same steps on your own site: https://<your site>/settings/personal-access-tokens/new (fine-grained) or https://<your site>/settings/tokens/new (classic). API URL: https://<your site>/api/v3.
GitLab (gitlab.com)
Signed in to GitLab, open gitlab.com/-/user_settings/personal_access_tokens — or your avatar › Edit profile › Access tokens (older versions: Preferences › Access Tokens).
Add new token: a name (
PWO) and an expiration date (GitLab requires one, at most a year).Scopes:
Scope Gives apireading, saving, branches, merge requests, members — needed to save read_apireading only (open files and folders, see members) read_repositoryandwrite_repositoryare not enough: they are forgit clone/git push, not for the web API Progressive Web Office uses.Create personal access token, copy it (
glpat-…).
The token never gives more than your role in the project: saving needs the role Developer or above — and Maintainer on a protected branch (usually main); a Reporter or Guest can only read.
Instead of a personal token, a project (or group) owner can create a project access token (project › Settings › Access tokens, role Developer, scope api): it reaches that project only.
Self-managed GitLab
The same steps on your own site: https://<your site>/-/user_settings/personal_access_tokens (before GitLab 16: https://<your site>/-/profile/personal_access_tokens). API URL: https://<your site>/api/v4. The site must accept requests from a web page (CORS), as gitlab.com does; ask its administrator if every request fails with a network error.
Gitea and Forgejo (Codeberg, self-hosted, local network)
Choose Gitea / Forgejo as the service; the API URL is https://<site>/api/v1 (https://codeberg.org/api/v1 for Codeberg). An address such as https://codeberg.org/owner/repo/src/branch/main/a.odt opens directly; on another site, add an account first so that the site is known as a Gitea / Forgejo one.
- Signed in to the site, open Settings → Applications (
https://<site>/user/settings/applications). - Under Manage access tokens, name the token (e.g.
PWO). - In Select permissions, give repository: Read and write — and user: Read, to list your repositories.
- Generate token, copy it (shown only once) and paste it in Progressive Web Office.
A forge on the local network works the same, with two conditions set by the browser:
it must be reached over HTTPS (a page served over HTTPS cannot call an
http://address), with a certificate the device trusts — or run Progressive Web Office itself from the local network overhttp://;it must accept requests from the page (CORS). In Gitea's or Forgejo's
app.ini:ini[cors] ENABLED = true ALLOW_DOMAIN = https://progressive-web-office.github.io METHODS = GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS HEADERS = Content-Type,Authorization(replace the domain with the address the application is served from).
Saving several changes in one commit (a repository opened as a folder) needs Gitea 1.20 or Forgejo 1.20 or later.
Other forges
Bitbucket, Gogs and others are not supported yet.
Token storage
The token is stored only in this browser (local storage) — or only in memory when Remember the token is unticked — and is sent only to the API URL of its account. It is never written into documents, drafts, exported files, backups or logs. Use Forget to delete it from this device, and revoke it on the forge if the device is lost.
Who can see a repository, and who works on it
Once a repository is chosen, the window tells:
- its visibility: 🌐 Public (anyone on the Internet can see it and its history; only its collaborators can change it), 🔒 Private (only its collaborators, and members of its organisation or group as allowed), or 🏢 Internal on GitLab (every signed-in user of the site);
- your role (GitHub: Read, Triage, Write, Maintain, Admin; GitLab: Guest, Planner, Reporter, Developer, Maintainer, Owner) and whether you can save there;
- Collaborators and their roles, opened on demand. The services show them only to people allowed to write in the repository, and only with a token.
The same is shown for a repository opened as a folder (🔒, 🌐 or 🏢 in the folder panel), and the icon precedes the repository's name above a document opened from it.
Open a file
Paste its address, or pick a repository (or type owner/name for any repository you can read) and a branch, then browse the folders and click a file. Every supported format can be opened: documents, spreadsheets, presentations, PDF, Markdown, MDZ, LaTeX…
The header shows where the document comes from (🔒 owner/name · branch, the icon telling its visibility). Choosing another repository clears the one shown first: what is listed is always the repository you save to.
Commit changes
For a document opened from a repository, Save (Ctrl+S) commits it to the same path and branch. The commit dialog proposes a Conventional Commits message (docs: update report.docx) that you can edit, and lets you commit to another branch — tick Create this branch to create it from the current one.
Any other document can be saved to a repository with Commit…: paste the repository address (or choose the account, repository, branch and folder), then the file name. The extension selects the format (for example .md, .docx, .tex).
Prefer text formats in a repository
Git shows what changed between two versions line by line — but only for text files. A .docx, .odt or .xlsx is a zip archive: each commit stores a new opaque file, and changes can be neither reviewed nor merged. So when saving to a repository, the Format list puts the text formats first (Markdown .md, LaTeX .tex, CSV .csv) and proposes one by default — report.docx becomes report.md, marks.xlsx becomes marks.csv. The binary formats stay available: choose one when you need its exact layout (a CSV keeps one sheet, without formatting).
An empty repository
A repository just created on GitHub or GitLab has no file and no branch yet. It opens without error and says so; save a document in it (Commit… or Save to repository): it becomes its first file, on its default branch. Opened as a folder, its first file is created the same way.
Save as… still downloads a local copy in any format.
Branches and pull requests from a document
The repository and branch shown in the header (owner/name · main) is a button:
- Work on a new branch… creates a branch from the current one (named
pwo/<date>unless you choose another name): the next saves are commits there, the default branch staying as it is; - Propose the changes to main… (on another branch) opens a pull request on GitHub, or a merge request on GitLab, under the title you give, and opens it in a new tab. Save first: changes not yet committed are not part of the request.
History of a document
Git keeps every committed version of every file. For a document of a repository, History of this document… — in the menu of the repository shown above the document (🔒 owner/name · main), or in ⎇ of the folder panel for the document open — lists the commits that changed it on the branch, newest first, with their message, author and date. For each one:
- Changes made — what that commit changed, compared with the one before;
- Compare with now — the differences between that version and the document as it is on screen, unsaved changes included;
- Open — the version replaces the content of the document, which stays where it is: read it, or save it to make it the newest one;
- Restore… — after a confirmation, a new commit puts that version back (
docs: restore report.md as of 1a2b3c4). Nothing of the history is lost: the versions in between stay, and can be restored in turn.
The versions kept in the browser (🕘 History, see Versions) can be compared the same way.
Comparing versions
The comparison shows, in one column:
- lines added (green,
+), removed (red, struck through,−), and changed, with the words that went struck through in red and those that came underlined in green; - unchanged lines folded around the changes (… 12 unchanged lines opens them);
- a count: 3 lines added, 1 removed, 2 changed.
What is compared depends on the file:
| File | Compared as |
|---|---|
| Markdown, LaTeX, CSV, code and other text files | their text, line by line |
Word (.docx), OpenDocument (.odt), MDZ | their text in Markdown: headings, emphasis, lists, tables, equations, citations |
Excel (.xlsx), OpenDocument spreadsheets (.ods) | their cells: sheet, cell, value or formula before and after |
| PDF, presentations, pictures | not compared: open each version |
This is why text formats are proposed first in a repository: their history reads line by line on the forge too.
A repository as a folder
Opening a file from a repository also shows the repository in the folder panel, with its whole tree, the file selected; 📁 Open the repository as a folder in the window opens it without a file.
Open a folder also lists your Git accounts (⎇): choose one, then a repository and a branch — or choose ⎇ GitHub / GitLab repository… and paste the repository address (https://github.com/owner/name, or …/tree/dev for a branch), the account being added if needed — and the repository opens in the folder panel like a folder of the device — tree, search, links between notes, master documents. Every change is a commit on that branch:
- saving a document of the repository (
docs: update report.md); - creating a document or a folder (a new folder holds an empty
.gitkeep, since Git keeps no empty folders); - renaming, moving (a folder with everything in it, in one commit) and deleting files and folders in the explorer.
The whole tree is read in one request, so large repositories open quickly. If a file changed in the repository since you opened it, saving it is refused instead of overwriting the other change: reload the folder (↻) and open it again.
Branches and pull requests
⎇ next to the folder's name works with the branches of the repository:
- Work on a new branch… starts a branch from the one open (named
pwo/<date>unless you choose another name) and opens it: your changes are committed there, the default branch staying as it is; - Open another branch switches the folder to another branch;
- Propose the changes to main… (on a branch other than the default one) opens a pull request on GitHub, or a merge request on GitLab, from this branch to the default one, under the title you give, and opens it in a new tab to describe it, ask for reviews and merge it.
The token needs the right to create pull requests (GitHub fine-grained token: Pull requests: read and write; GitLab: the api scope).
Conflicts
If the file changed in the repository since you opened it (someone else committed), Progressive Web Office never overwrites it. You can instead:
- Save on a new branch — a
pwo/<date>branch is created from the current one and your version is committed there, ready for a pull/merge request; - Save as a copy next to it — your version is committed under a new name (
report-copy-<date>.docx).
Git on your own computer or network
Git does not need GitHub or GitLab: a folder of your computer, or of a shared drive of the local network, can be a Git working copy (made with git clone or git init).
- Open a folder → A folder of this device and choose the working copy: the panel shows ⎇ branch at the top (the
.gitfolder itself is hidden). Documents are saved in place, as plain files; commit them with your own Git tool (command line, VS Code, GitHub Desktop, GitKraken…). Git, not the application, keeps the versions:git log,git diffandgit checkoutwork on them as on any file. Prefer the text formats (.md,.tex,.csv,.fodt…) when you want readable diffs (see GIT-010). - Or let the application commit: when the working copy can be written (a folder of this device in Chrome or Edge, or the browser storage), the application makes the commits itself, as the
gitcommand would (it uses isomorphic-git, entirely in the browser):- Save offers a commit of the document: a message (
docs: update notes.md), the files to include; Not now leaves it to later. Tick Do not offer a commit at each save in this folder to stop being asked; - ⎇ branch, at the top of the panel: Commit this document…, Commit all the changes… (new, modified and deleted files, chosen one by one), History of this document… (the local commits, each compared with the one before or with the document as it is now, opened or restored — a restore is a new commit, the history stays as it is), and turning the offer at each save on or off;
- the author is the
user.name/user.emailof the repository's own.git/config, else your name from the settings; - large repositories work, packed objects included; the files are written in place, and a later
git statusin a terminal shows nothing to commit. Pushing to and pulling from a remote is still done with your Git tool.
- Save offers a commit of the document: a message (
- New documents right there: in the folder panel, 📝, 📊 and 📽️ create a text document, a spreadsheet or a presentation in the selected folder (in the format family of the settings) and open it; a drawing is in the right-click menu. In a repository opened as a folder (see below), the same buttons create the file as a commit, and each Save is a commit too.
Repositories used, and where documents come from
Repositories used. Every repository you open a file from, or commit to, is listed on the start screen under Repositories and servers used (with the WebDAV / Nextcloud folders). A click opens it again at once, in the folder of the last file, even for reading without an account. × forgets one, Forget them all forgets the list (accounts and files are not touched). To remember nothing, untick Remember the repositories and servers used in Settings → General.
Where a document comes from. A document opened from a repository, or committed to one, keeps its address — for instance https://github.com/me/notes/blob/main/report.odt:
- in the recent files, for every kind of document: reopened from there, even after closing the browser, it is tied to its repository again, and Save shows the commit dialog as usual;
- in its own properties (Document properties → Source) for OpenDocument and Microsoft Office text documents and presentations, and MDZ: a copy downloaded and opened later, on this device or another one with an account for the site, goes back to the same file. A Markdown file gets no front matter just for this (a
README.mdstays as it is).
A copy saved in another format (a .md of the repository saved as .odt) is another file: it is not tied to the repository. When the document is tied again, the file in the repository is read once more before the commit, and a change made there meanwhile is still detected the next times. ✕ Detach, beside the repository name at the top, unties the document (its Source property is cleared too). To keep no origin at all, untick Keep where documents come from in the settings.
When something goes wrong
| Message | Likely cause | What to do |
|---|---|---|
| 401 / Bad credentials | token mistyped, expired or revoked | Forget the account, create a new token, add it again |
| 403 | the token lacks a right (Contents: Read and write, scope api), the organisation has not approved it, or SSO is not authorised | check the token's rights on the forge; ask an organisation owner |
| … is private, or does not exist / 404 | wrong address, or the repository is not among those chosen for the token | check the address; edit the token to add the repository |
| You can read, not save here | your role is read only (GitHub Read/Triage, GitLab Reporter/Guest) | ask an owner for the Write / Developer role |
saving refused on main (GitLab) | protected branch | save on a new branch and propose a merge request |
| Network error | offline, or a self-managed site refusing requests from web pages (CORS) | check the connection; ask the site's administrator |
| The file changed in the repository | someone committed meanwhile | see Conflicts |