noren 0.1.0__tar.gz

noren-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.nf/tmp/
+.nf/logs/
+.nf/research/
+src/noren/_version.py
+dist/
+__pycache__/

noren-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 minamik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

noren-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.5
+Name: noren
+Version: 0.1.0
+Summary: Send selected files from one git repository to another as a single commit
+Project-URL: Repository, https://github.com/sync-dev-org/noren
+Author-email: minamik <10973755+minamikik@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6.0.3
+Description-Content-Type: text/markdown
+
+# noren
+
+[日本語](README.ja.md)
+
+noren sends selected files from one Git repository to another as a single commit; it does not publish packages to a registry.
+
+Use it, for example, to send a public snapshot of a private repository to GitHub. The destination receives the selected files, the commit message you supply, and the configured author and committer. Source commits, their messages, and annotated-tag messages are not copied. File paths and file contents that you select are copied.
+
+## Install and choose how to run
+
+You need Python 3.12 or later, Git, and [uv](https://docs.astral.sh/uv/). Run commands inside the source Git repository.
+
+Add noren as a development dependency of your Python project:
+
+```sh
+uv add --dev noren
+uv run noren --help
+```
+
+Alternatively, [uvx](https://docs.astral.sh/uv/guides/tools/) runs noren in an isolated environment without adding it to your project's dependencies:
+
+```sh
+uvx noren --help
+```
+
+The examples below use `uv run noren`. If you chose uvx, replace that prefix with `uvx noren`. If noren is already available in your environment, you can use `noren` directly. `noren init` and `noren publish` work without interactive input.
+
+## Initial setup
+
+The source repository must have an `origin` remote. Create a separate destination repository on GitHub and make sure your usual Git authentication can read it and push to it. noren uses `https://github.com/OWNER/REPO.git`, with your existing Git configuration.
+
+```sh
+uv run noren init
+```
+
+`noren init` takes no arguments and creates `noren.yaml` and `noren-words.txt` at the source repository root, even when run from a subdirectory. It prints setup instructions, exits with 0 on success, and reports errors to stderr with a nonzero exit code. It refuses to overwrite either file and creates neither file if `origin` is missing.
+
+### Configure noren.yaml
+
+Edit the generated template. This example sends `README.md`, `LICENSE`, and files under `src/`, except `src/internal/`. Replace `OWNER/public-project` with your destination:
+
+```yaml
+destination: OWNER/public-project
+include: |
+  README.md
+  LICENSE
+  src/
+exclude: |
+  src/internal/
+  private/
+  tests/
+  .github/
+  .nf/
+  .gitignore
+  pyproject.toml
+  uv.lock
+  noren.yaml
+  noren-words.txt
+word-list: noren-words.txt
+author:
+  name: Release Bot
+  email: release@example.invalid
+```
+
+| Key | What to write |
+| --- | --- |
+| `destination` | The destination's GitHub `OWNER/REPO`, rather than a URL. The source repository itself is rejected. |
+| `include` | Files to send, as a multiline string in `.gitignore` syntax. |
+| `exclude` | Files to leave out, in the same syntax. If both lists match a file, `exclude` wins. |
+| `word-list` | The forbidden-word file's path, relative to the repository root. The file must be inside the repository. |
+| `author` | Optional `name` and `email`. Both the destination commit's author and committer use these values. Replace the example identity with yours. |
+
+Every file in the tagged source tree must match `include` or `exclude`; a file in neither list stops the command. These lists classify tracked files in the tag, not untracked files in the working directory. Each list follows Git's `.gitignore` rules, including `#` comments, `!` negation, `/`-anchored paths, and `**`. Within a list, later matching rules take precedence. A negated child pattern cannot bring back a file while its parent directory remains excluded.
+
+Keep the configuration and forbidden-word file in `exclude`, and add rules for any other tracked files in your repository. If you change `word-list`, update its exclusion too. All four required keys must be present; an explicitly empty `include` or `exclude` string is allowed, but every file still needs classification.
+
+If you omit `author`, noren uses the authenticated [GitHub CLI](https://cli.github.com/) account when `gh` is available: its name (or username if the name is empty) and `ID+USERNAME@users.noreply.github.com`. If that account cannot be obtained, noren stops and asks you to configure `author.name` and `author.email`. `gh` is optional and only supplies this default identity; push authentication comes from Git.
+
+For SSH authentication, you can configure Git to rewrite the GitHub HTTPS URLs inside this source repository:
+
+```sh
+git config --local url."git@github.com:".insteadOf https://github.com/
+```
+
+### Configure noren-words.txt
+
+Write one forbidden word or phrase per line. The generated file already contains the source `origin` URL and its repository name. Keep those entries and add identifiers or text that must not appear in selected file contents. For example, with `origin` set to `git@github.com:OWNER/source-private.git`:
+
+```text
+git@github.com:OWNER/source-private.git
+source-private
+internal-project
+private@example.invalid
+```
+
+The list must contain at least one nonblank line. Every nonblank line is an entry, including a line beginning with `#`; the word list has no comment syntax. noren compares substrings after Unicode NFKC normalization and case folding, so case and full-width forms also match. Bytes that cannot be decoded as UTF-8 are replaced for the inspection. The files are sent with their original bytes.
+
+### Commit the settings before selecting a tag
+
+noren reads the selected files, `noren.yaml`, and the word list from the commit named by `--tag`. Changes in the working directory or later commits do not affect that tag's check or publication.
+
+Commit the source files you intend to send, then commit the settings and create the source tag you will use:
+
+```sh
+git add noren.yaml noren-words.txt
+git commit -m "Configure noren"
+git tag v1.0.0
+```
+
+If you correct settings or file contents after a failed check, commit the correction and choose a tag that contains it before checking again.
+
+## Check before sending
+
+`noren publish` defaults to dry-run. Both `--tag` and `--message` are required, even for a check. For the first publication, when the destination has no `main` branch:
+
+```sh
+uv run noren publish --tag v1.0.0 --message "Release v1.0.0" --initial
+```
+
+For a tag containing only `README.md` and `src/app.py` among the included files, a successful first check prints:
+
+```yaml
+tag: v1.0.0
+destination: OWNER/public-project
+files:
+- README.md
+- src/app.py
+destination_main_before: null
+commit: null
+pushed: false
+```
+
+Check `destination` and every path in `files`. Dry-run creates no destination commit and updates no destination branches or tags, but it reads the destination's references, so Git access is needed. It also resolves the author identity. A successful dry-run does not guarantee permission to push.
+
+The command exits with 0 if the check succeeds. It exits with a nonzero code and writes the reason to stderr if, for example, a file is in neither list, selected contents contain a forbidden word, a required setting or a nonempty word list is missing, or the destination cannot be read. Unclassified-file errors list paths; forbidden-word errors identify the file and line. Selected submodules must be excluded; symlinks are inspected using their link target text and sent as symlinks.
+
+Use `--initial` only when destination `main` is absent, for both dry-run and push. noren stops if `--initial` is given and `main` already exists, or if `--initial` is omitted and `main` does not exist. An existing destination tag of the requested name also stops publication.
+
+## Send the checked files
+
+Add `--push` to the command you checked:
+
+```sh
+uv run noren publish --tag v1.0.0 --message "Release v1.0.0" --initial --push
+```
+
+The first publication creates a commit with no parent. Each later publication adds one commit whose only parent is the destination's previous `main` tip. Its tree contains exactly the selected source files; files absent from the selection are absent from the new destination tree. noren updates destination `main` and a tag with the source tag's name together in one atomic push, without force. The destination tag points directly to the new commit, even if the source tag is annotated.
+
+For a later source tag, omit `--initial`:
+
+```sh
+uv run noren publish --tag v1.1.0 --message "Release v1.1.0"
+uv run noren publish --tag v1.1.0 --message "Release v1.1.0" --push
+```
+
+Choose a destination commit message appropriate for the files you are sending. noren uses that message instead of the source commit messages.
+
+## Verify the result
+
+`noren publish` writes one YAML document to stdout on success and failure. Save this document and stderr, and check the exit code. To save the output of the later push above, use this form in place of that push command:
+
+```sh
+uv run noren publish --tag v1.1.0 --message "Release v1.1.0" --push > /tmp/noren-result.yaml 2> /tmp/noren-error.txt
+```
+
+| Key | Meaning |
+| --- | --- |
+| `tag` | The requested source tag name; an empty string if unavailable. |
+| `destination` | The destination `OWNER/REPO`; an empty string if unavailable. |
+| `files` | The selected file paths as a YAML list, possibly empty. This list alone does not indicate a successful check or push. |
+| `destination_main_before` | The destination's `main` commit ID read before sending. `null` means the destination was read and `main` was absent; `''` means that value could not be obtained. |
+| `commit` | The created destination commit ID. `null` for dry-run or a failure before creating a commit. |
+| `pushed` | `true` when Git reported that destination `main` and the tag were updated; `false` for dry-run or when the command could not confirm a successful push. |
+
+A successful push exits with 0 and has `pushed: true` and a non-null `commit`. The ID is the destination commit's ID, not the source commit's ID.
+
+If a push fails or its result is uncertain and `commit` is non-null, keep that ID and `destination_main_before`. `pushed: false` by itself cannot establish whether the remote received the update. Read the destination references, replacing the example repository and tag with those in your result:
+
+```sh
+git ls-remote --refs https://github.com/OWNER/public-project.git refs/heads/main refs/tags/v1.1.0
+```
+
+If both references show the printed `commit` ID, the update is present. If `main` has advanced since then, a matching tag still identifies the published snapshot; check the destination history to confirm that commit is an ancestor of the current `main`. If `main` still equals `destination_main_before` and the tag is absent, the update is not present at the time of the check. If the references differ otherwise, inspect the destination history before deciding what to do. A failed `ls-remote` does not establish whether the push succeeded. Do not infer the result from the exit code alone or blindly repeat the initial command: existing `main` or an existing tag will stop it.
+
+## Command help
+
+```sh
+uv run noren --help
+uv run noren init --help
+uv run noren publish --help
+```
+
+Command help is in English. This README covers setup, checks, sending, and verification. Your project's version changes, builds, and publication to package registries belong to its own release instructions.

noren-0.1.0/README.ja.md

@@ -0,0 +1,193 @@
+# noren
+
+[English](README.md)
+
+noren は、Git リポジトリで選んだファイルを別のリポジトリへ一つの commit として送るコマンドです。パッケージのレジストリへの公開は行いません。
+
+例えば、private のリポジトリから公開するファイルを選び、GitHub に送るために使います。送り先には、選んだファイル、指定した commit message、設定した author と committer が置かれます。元の commit、その message、注釈付き tag の message はコピーされません。選んだファイルの path と中身はコピーされます。
+
+## インストールと実行方法
+
+Python 3.12 以上、Git、[uv](https://docs.astral.sh/uv/) が必要です。コマンドは元の Git リポジトリの中で実行します。
+
+Python プロジェクトの開発時の依存として noren を追加する場合:
+
+```sh
+uv add --dev noren
+uv run noren --help
+```
+
+プロジェクトの依存に追加せずに使う場合は、[uvx](https://docs.astral.sh/uv/guides/tools/) で隔離された実行環境から起動できます。
+
+```sh
+uvx noren --help
+```
+
+以下の例は `uv run noren` を使います。uvx を選んだ場合は、その部分を `uvx noren` に置き換えてください。すでに実行環境から noren を起動できる場合は、`noren` を直接使えます。`noren init` と `noren publish` は対話の入力を求めません。
+
+## 初期セットアップ
+
+元のリポジトリには remote の `origin` が必要です。GitHub に別の送り先リポジトリを作り、普段使っている Git の認証で読み取りと push ができるようにしてください。noren は、既存の Git の設定で `https://github.com/OWNER/REPO.git` にアクセスします。
+
+```sh
+uv run noren init
+```
+
+`noren init` は引数を取らず、元のリポジトリの root に `noren.yaml` と `noren-words.txt` を作ります。サブディレクトリから実行した場合も同じです。成功時は設定の案内を標準出力に出し、終了コード 0 で終わります。失敗時は理由を標準エラー出力に出し、0 以外で終わります。どちらかのファイルがすでにあれば上書きせずに止まり、`origin` が無い場合はどちらのファイルも作りません。
+
+### noren.yaml を設定する
+
+生成された雛形を編集します。次の例は `README.md`、`LICENSE`、`src/` の下のファイルを送り、`src/internal/` は外します。`OWNER/public-project` は送り先に置き換えてください。
+
+```yaml
+destination: OWNER/public-project
+include: |
+  README.md
+  LICENSE
+  src/
+exclude: |
+  src/internal/
+  private/
+  tests/
+  .github/
+  .nf/
+  .gitignore
+  pyproject.toml
+  uv.lock
+  noren.yaml
+  noren-words.txt
+word-list: noren-words.txt
+author:
+  name: Release Bot
+  email: release@example.invalid
+```
+
+| key | 書く内容 |
+| --- | --- |
+| `destination` | 送り先の GitHub の `OWNER/REPO`。URL ではありません。元のリポジトリ自身を指定すると止まります。 |
+| `include` | 送るファイルの一覧。`.gitignore` の書式のまま、複数行の文字列で書きます。 |
+| `exclude` | 送らないファイルの一覧。同じ書式で書きます。両方の一覧に当たるファイルは `exclude` が優先されます。 |
+| `word-list` | 禁止語の一覧のファイルの path。リポジトリの root からの相対 path で、リポジトリの中のファイルを指定します。 |
+| `author` | 任意の `name` と `email`。送り先の commit の author と committer の両方に使います。例の値は利用する名義に置き換えてください。 |
+
+元の tag の tree にあるファイルは、すべて `include` または `exclude` に当たる必要があります。どちらにも無いファイルがあると、コマンドは止まります。一覧の対象は tag に記録されたファイルで、working directory の未追跡のファイルは対象にしません。各一覧は Git の `.gitignore` の規則に従い、`#` の comment、`!` の否定、`/` による root への固定、`**` を使えます。同じ一覧の中では後に書いた一致する規則が優先されます。親のディレクトリが除外されたままでは、子のファイルを否定の pattern だけで戻すことはできません。
+
+設定ファイルと禁止語の一覧のファイルは `exclude` に残し、リポジトリの他の追跡するファイルも一覧に加えてください。`word-list` を変えた場合は、そのファイルの除外も更新します。必須の四つの key はすべて必要です。`include` または `exclude` を空の文字列として設定することはできますが、どのファイルも分類する必要があります。
+
+`author` を省いた場合、noren は [GitHub CLI](https://cli.github.com/) の `gh` が使える時に、認証済み account の名前 (名前が空なら username) と `ID+USERNAME@users.noreply.github.com` を使います。account を取得できない場合は止まり、`author.name` と `author.email` の設定を求めます。`gh` は任意で、この既定の名義を作るためだけに使います。push の認証は Git の設定を使います。
+
+SSH の認証を使う場合は、この元のリポジトリの中で GitHub の HTTPS URL を書き換えるよう Git に設定できます。
+
+```sh
+git config --local url."git@github.com:".insteadOf https://github.com/
+```
+
+### noren-words.txt を設定する
+
+禁止する語や文を一行に一つずつ書きます。生成されたファイルには、元の `origin` の URL とリポジトリの名前が入っています。その二つを残し、送るファイルの中身に含まれてはいけない識別子や文を加えてください。例えば、`origin` が `git@github.com:OWNER/source-private.git` の場合:
+
+```text
+git@github.com:OWNER/source-private.git
+source-private
+internal-project
+private@example.invalid
+```
+
+一覧には空白でない行が一つ以上必要です。`#` で始まる行も含め、空白でない行はすべて禁止語になります。禁止語の一覧には comment の書式はありません。noren は Unicode の NFKC 正規化と case folding の後に部分一致で探すため、大文字と小文字の違い、全角の表記でも当たります。UTF-8 として読めない byte は、検査の際に置き換え文字として扱います。送るファイルの byte は元のままです。
+
+### 設定を commit してから tag を指定する
+
+noren は、`--tag` が指す commit から、送るファイル、`noren.yaml`、禁止語の一覧を読みます。working directory や後の commit で変更しても、その tag の検査や送信には反映されません。
+
+送る予定の元のファイルを commit した後、設定を commit し、使う元の tag を作ります。
+
+```sh
+git add noren.yaml noren-words.txt
+git commit -m "Configure noren"
+git tag v1.0.0
+```
+
+検査で止まった後に設定やファイルの中身を直した場合は、修正を commit し、その修正を含む tag を選んでから、もう一度検査してください。
+
+## 送る前に確認する
+
+`noren publish` の既定の動作は dry-run です。検査の場合も `--tag` と `--message` は必須です。最初の一回で、送り先に `main` branch が無い場合:
+
+```sh
+uv run noren publish --tag v1.0.0 --message "Release v1.0.0" --initial
+```
+
+送る一覧に当たるファイルが `README.md` と `src/app.py` の二つだけの tag なら、最初の検査の成功時に次の結果を出します。
+
+```yaml
+tag: v1.0.0
+destination: OWNER/public-project
+files:
+- README.md
+- src/app.py
+destination_main_before: null
+commit: null
+pushed: false
+```
+
+`destination` と `files` の各 path を確認してください。dry-run は送り先の commit を作らず、送り先の branch と tag を更新しません。ただし、送り先の参照を読むので、Git のアクセスが必要です。author の名義も確認します。dry-run の成功は push の権限を保証しません。
+
+検査が成功すると、コマンドは終了コード 0 で終わります。どちらの一覧にも無いファイルがある場合、送る中身に禁止語がある場合、必須の設定や語を含む禁止語の一覧が無い場合、送り先を読めない場合などは、0 以外で終わり、理由を標準エラー出力に出します。未分類のファイルのエラーは path を示し、禁止語のエラーはファイルと行を示します。送る一覧に当たる submodule は除外する必要があります。symlink はリンク先の文字列を検査し、symlink のまま送ります。
+
+dry-run と push のどちらも、送り先に `main` が無い時だけ `--initial` を使います。`--initial` があって `main` が存在する場合と、`--initial` が無く `main` が存在しない場合は止まります。送り先に指定した名前の tag がすでにある場合も止まります。
+
+## 確認したファイルを送る
+
+確認したコマンドに `--push` を加えます。
+
+```sh
+uv run noren publish --tag v1.0.0 --message "Release v1.0.0" --initial --push
+```
+
+最初の一回は、親の無い commit を作ります。次からは、送り先の直前の `main` の先端だけを親にした commit を一つ足します。その tree は選んだ元のファイルだけを持ち、選んだ一覧に無いファイルは新しい送り先の tree に残りません。noren は、送り先の `main` と元の tag と同じ名前の tag を、force を使わず、一回の atomic push で一緒に更新します。元の tag が注釈付きでも、送り先の tag は新しい commit を直接指します。
+
+次の元の tag を送る時は `--initial` を外します。
+
+```sh
+uv run noren publish --tag v1.1.0 --message "Release v1.1.0"
+uv run noren publish --tag v1.1.0 --message "Release v1.1.0" --push
+```
+
+送るファイルに合った送り先の commit message を指定してください。noren は元の commit message の代わりに、その message を使います。
+
+## 送った結果を確かめる
+
+`noren publish` は成功時も失敗時も、一つの YAML 文書を標準出力に出します。その文書と標準エラー出力を保存し、終了コードを確認してください。上の次回の push の出力を保存する場合は、その push のコマンドの代わりに次の形を使います。
+
+```sh
+uv run noren publish --tag v1.1.0 --message "Release v1.1.0" --push > /tmp/noren-result.yaml 2> /tmp/noren-error.txt
+```
+
+| key | 意味 |
+| --- | --- |
+| `tag` | 指定した元の tag の名前。取得できない場合は空の文字列です。 |
+| `destination` | 送り先の `OWNER/REPO`。取得できない場合は空の文字列です。 |
+| `files` | 選んだファイルの path の YAML の list。空の場合もあります。この一覧だけでは検査や push の成功は分かりません。 |
+| `destination_main_before` | 送る前に読んだ送り先の `main` の commit の ID。`null` は送り先を読めて `main` が無かった場合、`''` は値を取得できなかった場合です。 |
+| `commit` | 作った送り先の commit の ID。dry-run の時と、commit を作る前に止めた時は `null` です。 |
+| `pushed` | Git が送り先の `main` と tag の更新を成功と報告した場合は `true`。dry-run の時と、コマンドが push の成功を確認できなかった場合は `false` です。 |
+
+push の成功時は終了コードが 0 で、`pushed: true` となり、`commit` は `null` 以外の値になります。この ID は送り先の commit の ID で、元の commit の ID ではありません。
+
+push が失敗した場合や結果が不明な場合に、`commit` が `null` 以外なら、その ID と `destination_main_before` を残してください。`pushed: false` だけでは、送り先が更新を受け取ったかは決まりません。結果にあるリポジトリと tag に例を置き換え、送り先の参照を読みます。
+
+```sh
+git ls-remote --refs https://github.com/OWNER/public-project.git refs/heads/main refs/tags/v1.1.0
+```
+
+両方の参照が出力された `commit` の ID を示す場合、更新は送り先にあります。その後に `main` が進んだ場合も、tag が同じ ID なら送った時のファイルを特定できます。送り先の履歴を見て、その commit が現在の `main` の祖先かを確かめてください。`main` が `destination_main_before` のままで tag が無い場合、確認した時点では更新がありません。他の値になっている場合は、送り先の履歴を調べてから次の操作を決めてください。`ls-remote` の失敗では、push の成否は分かりません。終了コードだけで結果を決めたり、初回のコマンドをそのまま繰り返したりしないでください。すでに `main` や tag があれば、コマンドは止まります。
+
+## コマンドの help
+
+```sh
+uv run noren --help
+uv run noren init --help
+uv run noren publish --help
+```
+
+コマンドの help は英語です。この README は初期セットアップ、検査、送信、結果の確認を扱います。プロジェクトの version の変更、build、パッケージのレジストリへの公開は、そのプロジェクトの release の手順を参照してください。

noren-0.1.0/README.md

@@ -0,0 +1,193 @@
+# noren
+
+[日本語](README.ja.md)
+
+noren sends selected files from one Git repository to another as a single commit; it does not publish packages to a registry.
+
+Use it, for example, to send a public snapshot of a private repository to GitHub. The destination receives the selected files, the commit message you supply, and the configured author and committer. Source commits, their messages, and annotated-tag messages are not copied. File paths and file contents that you select are copied.
+
+## Install and choose how to run
+
+You need Python 3.12 or later, Git, and [uv](https://docs.astral.sh/uv/). Run commands inside the source Git repository.
+
+Add noren as a development dependency of your Python project:
+
+```sh
+uv add --dev noren
+uv run noren --help
+```
+
+Alternatively, [uvx](https://docs.astral.sh/uv/guides/tools/) runs noren in an isolated environment without adding it to your project's dependencies:
+
+```sh
+uvx noren --help
+```
+
+The examples below use `uv run noren`. If you chose uvx, replace that prefix with `uvx noren`. If noren is already available in your environment, you can use `noren` directly. `noren init` and `noren publish` work without interactive input.
+
+## Initial setup
+
+The source repository must have an `origin` remote. Create a separate destination repository on GitHub and make sure your usual Git authentication can read it and push to it. noren uses `https://github.com/OWNER/REPO.git`, with your existing Git configuration.
+
+```sh
+uv run noren init
+```
+
+`noren init` takes no arguments and creates `noren.yaml` and `noren-words.txt` at the source repository root, even when run from a subdirectory. It prints setup instructions, exits with 0 on success, and reports errors to stderr with a nonzero exit code. It refuses to overwrite either file and creates neither file if `origin` is missing.
+
+### Configure noren.yaml
+
+Edit the generated template. This example sends `README.md`, `LICENSE`, and files under `src/`, except `src/internal/`. Replace `OWNER/public-project` with your destination:
+
+```yaml
+destination: OWNER/public-project
+include: |
+  README.md
+  LICENSE
+  src/
+exclude: |
+  src/internal/
+  private/
+  tests/
+  .github/
+  .nf/
+  .gitignore
+  pyproject.toml
+  uv.lock
+  noren.yaml
+  noren-words.txt
+word-list: noren-words.txt
+author:
+  name: Release Bot
+  email: release@example.invalid
+```
+
+| Key | What to write |
+| --- | --- |
+| `destination` | The destination's GitHub `OWNER/REPO`, rather than a URL. The source repository itself is rejected. |
+| `include` | Files to send, as a multiline string in `.gitignore` syntax. |
+| `exclude` | Files to leave out, in the same syntax. If both lists match a file, `exclude` wins. |
+| `word-list` | The forbidden-word file's path, relative to the repository root. The file must be inside the repository. |
+| `author` | Optional `name` and `email`. Both the destination commit's author and committer use these values. Replace the example identity with yours. |
+
+Every file in the tagged source tree must match `include` or `exclude`; a file in neither list stops the command. These lists classify tracked files in the tag, not untracked files in the working directory. Each list follows Git's `.gitignore` rules, including `#` comments, `!` negation, `/`-anchored paths, and `**`. Within a list, later matching rules take precedence. A negated child pattern cannot bring back a file while its parent directory remains excluded.
+
+Keep the configuration and forbidden-word file in `exclude`, and add rules for any other tracked files in your repository. If you change `word-list`, update its exclusion too. All four required keys must be present; an explicitly empty `include` or `exclude` string is allowed, but every file still needs classification.
+
+If you omit `author`, noren uses the authenticated [GitHub CLI](https://cli.github.com/) account when `gh` is available: its name (or username if the name is empty) and `ID+USERNAME@users.noreply.github.com`. If that account cannot be obtained, noren stops and asks you to configure `author.name` and `author.email`. `gh` is optional and only supplies this default identity; push authentication comes from Git.
+
+For SSH authentication, you can configure Git to rewrite the GitHub HTTPS URLs inside this source repository:
+
+```sh
+git config --local url."git@github.com:".insteadOf https://github.com/
+```
+
+### Configure noren-words.txt
+
+Write one forbidden word or phrase per line. The generated file already contains the source `origin` URL and its repository name. Keep those entries and add identifiers or text that must not appear in selected file contents. For example, with `origin` set to `git@github.com:OWNER/source-private.git`:
+
+```text
+git@github.com:OWNER/source-private.git
+source-private
+internal-project
+private@example.invalid
+```
+
+The list must contain at least one nonblank line. Every nonblank line is an entry, including a line beginning with `#`; the word list has no comment syntax. noren compares substrings after Unicode NFKC normalization and case folding, so case and full-width forms also match. Bytes that cannot be decoded as UTF-8 are replaced for the inspection. The files are sent with their original bytes.
+
+### Commit the settings before selecting a tag
+
+noren reads the selected files, `noren.yaml`, and the word list from the commit named by `--tag`. Changes in the working directory or later commits do not affect that tag's check or publication.
+
+Commit the source files you intend to send, then commit the settings and create the source tag you will use:
+
+```sh
+git add noren.yaml noren-words.txt
+git commit -m "Configure noren"
+git tag v1.0.0
+```
+
+If you correct settings or file contents after a failed check, commit the correction and choose a tag that contains it before checking again.
+
+## Check before sending
+
+`noren publish` defaults to dry-run. Both `--tag` and `--message` are required, even for a check. For the first publication, when the destination has no `main` branch:
+
+```sh
+uv run noren publish --tag v1.0.0 --message "Release v1.0.0" --initial
+```
+
+For a tag containing only `README.md` and `src/app.py` among the included files, a successful first check prints:
+
+```yaml
+tag: v1.0.0
+destination: OWNER/public-project
+files:
+- README.md
+- src/app.py
+destination_main_before: null
+commit: null
+pushed: false
+```
+
+Check `destination` and every path in `files`. Dry-run creates no destination commit and updates no destination branches or tags, but it reads the destination's references, so Git access is needed. It also resolves the author identity. A successful dry-run does not guarantee permission to push.
+
+The command exits with 0 if the check succeeds. It exits with a nonzero code and writes the reason to stderr if, for example, a file is in neither list, selected contents contain a forbidden word, a required setting or a nonempty word list is missing, or the destination cannot be read. Unclassified-file errors list paths; forbidden-word errors identify the file and line. Selected submodules must be excluded; symlinks are inspected using their link target text and sent as symlinks.
+
+Use `--initial` only when destination `main` is absent, for both dry-run and push. noren stops if `--initial` is given and `main` already exists, or if `--initial` is omitted and `main` does not exist. An existing destination tag of the requested name also stops publication.
+
+## Send the checked files
+
+Add `--push` to the command you checked:
+
+```sh
+uv run noren publish --tag v1.0.0 --message "Release v1.0.0" --initial --push
+```
+
+The first publication creates a commit with no parent. Each later publication adds one commit whose only parent is the destination's previous `main` tip. Its tree contains exactly the selected source files; files absent from the selection are absent from the new destination tree. noren updates destination `main` and a tag with the source tag's name together in one atomic push, without force. The destination tag points directly to the new commit, even if the source tag is annotated.
+
+For a later source tag, omit `--initial`:
+
+```sh
+uv run noren publish --tag v1.1.0 --message "Release v1.1.0"
+uv run noren publish --tag v1.1.0 --message "Release v1.1.0" --push
+```
+
+Choose a destination commit message appropriate for the files you are sending. noren uses that message instead of the source commit messages.
+
+## Verify the result
+
+`noren publish` writes one YAML document to stdout on success and failure. Save this document and stderr, and check the exit code. To save the output of the later push above, use this form in place of that push command:
+
+```sh
+uv run noren publish --tag v1.1.0 --message "Release v1.1.0" --push > /tmp/noren-result.yaml 2> /tmp/noren-error.txt
+```
+
+| Key | Meaning |
+| --- | --- |
+| `tag` | The requested source tag name; an empty string if unavailable. |
+| `destination` | The destination `OWNER/REPO`; an empty string if unavailable. |
+| `files` | The selected file paths as a YAML list, possibly empty. This list alone does not indicate a successful check or push. |
+| `destination_main_before` | The destination's `main` commit ID read before sending. `null` means the destination was read and `main` was absent; `''` means that value could not be obtained. |
+| `commit` | The created destination commit ID. `null` for dry-run or a failure before creating a commit. |
+| `pushed` | `true` when Git reported that destination `main` and the tag were updated; `false` for dry-run or when the command could not confirm a successful push. |
+
+A successful push exits with 0 and has `pushed: true` and a non-null `commit`. The ID is the destination commit's ID, not the source commit's ID.
+
+If a push fails or its result is uncertain and `commit` is non-null, keep that ID and `destination_main_before`. `pushed: false` by itself cannot establish whether the remote received the update. Read the destination references, replacing the example repository and tag with those in your result:
+
+```sh
+git ls-remote --refs https://github.com/OWNER/public-project.git refs/heads/main refs/tags/v1.1.0
+```
+
+If both references show the printed `commit` ID, the update is present. If `main` has advanced since then, a matching tag still identifies the published snapshot; check the destination history to confirm that commit is an ancestor of the current `main`. If `main` still equals `destination_main_before` and the tag is absent, the update is not present at the time of the check. If the references differ otherwise, inspect the destination history before deciding what to do. A failed `ls-remote` does not establish whether the push succeeded. Do not infer the result from the exit code alone or blindly repeat the initial command: existing `main` or an existing tag will stop it.
+
+## Command help
+
+```sh
+uv run noren --help
+uv run noren init --help
+uv run noren publish --help
+```
+
+Command help is in English. This README covers setup, checks, sending, and verification. Your project's version changes, builds, and publication to package registries belong to its own release instructions.