Deterministic Upstream Orchestration Engine (git-pt)
====================================================

git-pt is a C-based Git orchestration tool for deterministically managing one or more upstreams.
It supports root mode and prefix mode (subtree-like), produces deterministic snapshots, and
tracks prefix sync state to enable incremental updates.

Highlights
----------
- Multi-upstream support (one root, many prefix)
- Deterministic snapshot IDs
- Prefix mode import into a subdirectory
- Mirror repositories under .pt/mirrors for fast sync
- Advisory locking and determinism guards
- Debug logging via PT_DEBUG=1

Build
-----
make

Install
-------
make install

If /usr/local/bin is not writable:
  sudo make install
or
  DESTDIR=$HOME/.local make install
  PATH=$HOME/.local/bin:$PATH

Quick Start
-----------
1) Initialize repo:
  git init
  git pt sync init

2) Add upstream (root mode):
  git pt add upstream <url> --channel <branch> --name <name>

3) Add upstream (prefix mode):
  git pt add upstream <url> --channel <branch> --name <name> --mode prefix --prefix vendor/<name>/

4) Sync:
  git pt rebase-upstream
  # or only one upstream
  git pt rebase-upstream --name <name>

5) Status:
  git pt status
  git pt status --json

6) Snapshot:
  git pt freeze-snapshot

Multi-Upstream Rules
--------------------
- At most one root upstream is allowed.
- Any number of prefix upstreams are allowed.
- Without --name, upstreams are applied in lexicographic name order.

Prefix Mode Behavior
--------------------
Prefix mode imports upstream content into the specified directory and creates a deterministic
merge commit. This provides:
- Upstream content under the prefix path
- A merge commit that records the upstream parent (history-preserving)
- Incremental updates when the upstream target changes

Debug Logging
-------------
Enable debug logs with:
  PT_DEBUG=1 git pt rebase-upstream

This prints per-upstream decisions and failure points.

.gitignore and .pt Directory
----------------------------
`git pt sync init` adds a .gitignore block for .pt. Recommended usage:
- Commit .pt/config.json to the repo
- Keep other .pt/* files as cache
- If `git clean -fdx` removes cache, re-run init/sync to regenerate it

Example (Prefix)
----------------
git pt sync init
git pt add upstream https://github.com/madler/zlib --channel master --name zlib --mode prefix --prefix vendor/zlib/
git pt rebase-upstream
ls vendor/zlib

Example (Root)
--------------
git pt sync init
git pt add upstream <url> --channel <branch> --name upstream
git pt rebase-upstream

Common Errors
-------------
Invalid branch:
  pt: unable to resolve channel <branch> for upstream <name>

Root mode with unrelated history:
  pt: no common ancestor for upstream <name> (root mode requires repo based on upstream)

License
-------
Copyright Notice:

Copyright (c) 2026 Project Tick and Mehmet Samet Duman

This software is provided “as is”, without any express or implied warranty.
In no event shall the authors or copyright holders be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it freely,
subject to the following conditions:
	1.	The origin of this software must not be misrepresented; you must not claim that you wrote the original software.
If you use this software in a product, an acknowledgment of Project Tick and Mehmet Samet Duman in the source code or documentation is required.
	2.	Altered source versions must be clearly marked as such and must not be misrepresented as being the original software.
	3.	This notice may not be removed or altered from any source distribution.

Project Tick                                                                Mehmet Samet Duman
projecttick@projecttick.org                                                 dumanmehmetsamet@icloud.com
Copyright (c) 2026 Project Tick                                             Copyright (c) 2026 Mehmet Samet Duman
Tepebaşı/Eskişehir/Türkiye                                                  Tepebaşı/Eskişehir/Türkiye