document untracked, direct, and update behaviors

docs/script.md

@@ -44,3 +44,47 @@ develop and preview your changes first.
 
 [uv]: https://docs.astral.sh/uv/
 [gh]: https://cli.github.com/
+
+## Automatic Commit
+
+After calling `modify`, the script will automatically add any tracked files
+and create a commit if it detects there are uncommitted changes.
+
+If you add a completely new file, it will not be tracked by Git yet, and this
+won't be detected or committed. Therefore, you should call
+{meth}`.Repo.add_files` to track any new files. Other modifications, such as
+changing an existing file or using {meth}`.Repo.rm_files`, will already be
+tracked by Git.
+
+You can set {attr}`.GitRepo.add_untracked` to also detect and add completely
+new untracked files. This is disabled by default as it might end up adding files
+that were generated as a side effect of other changes.
+
+```python
+class MyScript(GitHubScript):
+    def modify(self, repo: GitHubRepo) -> None:
+        repo.add_untracked = True
+        ...
+```
+
+## Merge vs PR
+
+By default, the GitHub provider creates PRs. You can instruct a repo to merge
+and push directly to the target instead. This is disabled by default because it
+provides one less opportunity to ensure your script worked correctly.
+
+Set {attr}`GitHubRepo.direct_submit` to `True` to enable this merge and push
+behavior.
+
+```python
+class MyScript(GitHubScript):
+    def modify(self, repo: GitHubRepo) -> None:
+        repo.direct_submit = True
+        ...
+```
+
+## Updating
+
+You may have run your script with submit enabled, then noticed that more is
+needed. If a branch and open PR already exist from a previous run of the script
+that, a force push will be used to update.