# Keeping docs up to date

How a push to your default branch updates the pages it affects, and how to review suggestions for pages you edited.

Docs go stale when code moves on. Docup closes that gap: when you push to your default branch, it works out which pages were written from the files you changed and brings them up to date. You review only what needs a human.

> **Note:** Updates on push need the repository to be connected through the Docup GitHub App. Projects created from a public link do not receive pushes. See [Connecting GitHub](/guides/connect-github).

## What starts an update

GitHub tells Docup about each push. An update starts for every project made from that repository when:

- the push is to the repository's default branch, and
- the project has finished its first docs run.

Pushes to other branches and branch deletions are ignored. A project still writing its first draft is left alone; the next push after it covers anything newer.

Pushes that arrive close together become one update. Docup waits for a minute of quiet, and runs at most 10 minutes after the first push in a burst. A project's updates also run one at a time.

## What an update does

1. **Read what changed.** Docup compares the last commit it documented with the current head of the branch and lists the changed files and commit messages. If the push changed 300 files or more, or the old commit no longer exists after a force push, Docup treats everything as possibly changed.
2. **Match files to pages.** Each page knows the files it was written from. A page is affected when one of them changed. Renamed files are followed, and deleted files are removed from the page's list.
3. **Handle new code.** Changed files that no page covers are looked at once. Docup decides, per file, whether it belongs in an existing page or can be ignored, such as tests, internal helpers, refactors and build files. Only when a push adds something users need that no page can cover does it plan new pages.
4. **Rewrite affected pages.** Pages are rewritten a few at a time. The writer receives the current page and the changed files, keeps the structure and wording where the code did not change, and fixes only what the change makes wrong or incomplete. If nothing needs to change, the page stays exactly as it is.

If no documented code changed, the update finishes without using the AI and does not count toward your daily limit.

## What happens to each page

| Situation | Result |
| --- | --- |
| The page is unedited and live | Rewritten and published. Readers see it, Ask AI learns it, and the cached site is cleared. |
| The page is unedited and still a draft | The draft is updated. It goes live when you publish. |
| You edited the page | The new text is saved as a suggestion for you to review. Your text is untouched. |
| You typed while the update was running | The result becomes a suggestion too. |
| Every file the page came from was deleted | The page is flagged, and nothing changes until you decide. |
| New code needs new pages | Up to 3 new draft pages are added per update. A site can grow to 30 pages through updates. |
| The page could not be updated | It keeps its text, and the run lists it as failed. |

New pages from an update are always drafts, even on a live site.

## Review a suggestion

A page with a pending suggestion shows **AI has an update for this page**, with the commit that caused it.

- **Review changes** opens the current page and the suggestion line by line, with additions in green and removals in red. Unchanged stretches are folded.
- **Apply update** replaces your draft with the suggestion. Readers see it after you publish. The page stays yours, so later pushes keep suggesting instead of overwriting.
- **Keep my version** closes the comparison and leaves the suggestion waiting.
- **Dismiss** throws the suggestion away.

## When the code was removed

If a push deletes every file a page was written from, the page shows **The code this page describes was removed**. Choose one:

- **Keep page** keeps it as your own page. It has no source files afterwards, so pushes no longer touch it.
- **Unpublish** takes it off the live site and keeps the draft. Shown only for live pages.
- **Delete page** removes it for good.

Until you choose, readers still see a live page.

## See what an update did

Every update appears in **Runs** as an update run. While an update runs, the page automatically refreshes every 4 seconds, displaying the current step: **Reading what changed**, **Deciding what the docs need**, or **Updating the pages**.

The run shows the commit and the previous commit it follows, with a link to view the commit on GitHub, and one line per page with its result:
- **Updated and published**
- **Draft updated**
- **Update to review**
- **New draft page**
- **Its code was removed**
- **Could not update**

If no documented code changed, the run displays **No docs changes needed** and shows **No page needed changes. The code that changed is not in the docs.** See [Runs](/guides/runs).

## Limits and failures

- A workspace can run 15 AI updates per day, counted by UTC day. Updates that change no documented code are free. Past the limit, the run fails with a message, and the next push after midnight UTC catches up.
- A failed update leaves the recorded commit where it was, so the next push covers its changes too.
- Updates are not retried automatically, because a retry would repeat every AI call.
- New files under the ignore paths in [AI guidance](/settings/guidance) are never read, so they are never documented.