feat: Add comprehensive documentation, contribution guidelines, issue/PR templates, code quality tools, and new test suites for submodules and credential helpers.

Author: linhay

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,22 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ""
+labels: bug
+assignees: ''
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**Reproduction steps**
+1. Steps to reproduce
+2. Expected behavior
+3. Actual behavior
+
+**Environment**
+- macOS / Linux
+- Swift version: `swift --version`
+
+**Additional context**
+Any other information, logs, or screenshots.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,16 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ""
+labels: enhancement
+assignees: ''
+---
+
+**Describe the feature**
+A clear and concise description of the desired feature.
+
+**Motivation**
+Why is this feature useful?
+
+**Design notes / constraints**
+Any API/design/compatibility considerations.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,12 @@
+## Summary
+
+Describe the change and why it is needed (1-3 sentences).
+
+## Checklist
+- [ ] I added/updated tests for changed behavior
+- [ ] I ran `swift test` locally
+- [ ] I updated `AGENTS.md`/`CONTRIBUTING.md` if I added formatting or linting
+- [ ] This change does not modify `Sources/SwiftGit/Resource/git-instance.bundle` unless intentional
+
+## Notes
+Additional context for reviewers, CI notes, or follow-ups.

.swiftformat

@@ -0,0 +1,9 @@
+--indent 4
+--line-length 120
+--exclude Sources/SwiftGit/Resource/git-instance.bundle
+--trimwhitespace always
+--stripunusedargs closure-only
+
+# Keep parentheses formatting conservative for readability
+--wraparguments before-first
+--removelinestrailingwhitespace always

.swiftlint.yml

@@ -0,0 +1,22 @@
+
+# Enable stricter defaults: avoid trailing whitespace and enforce line length
+disabled_rules: []
+
+opt_in_rules:
+  - empty_count
+  - explicit_init
+  - always_use_lowerCamelCase
+
+excluded:
+  - Sources/SwiftGit/Resource/git-instance.bundle
+
+line_length:
+  warning: 120
+  error: 160
+
+# Recommended autocorrect rules are not enabled by default; enable locally as needed
+disabled_by_default:
+  - nimble_operator
+  - prefer_self_in_static_references
+
+reporter: xcode

AGENTS.md

@@ -43,7 +43,10 @@ swift test --package-path . --filter <TestName>
     - SwiftLint: `brew install swiftlint` then `swiftlint lint` (or `swiftlint autocorrect`).
     - swift-format: follow Apple or community formatter and add a `.swift-format` config if you want automated formatting.
 
-  - If you add a formatter/linter, update this document and add its config to the repo root.
+- If you add a formatter/linter, update this document and add its config to the repo root.
+  - This repository now includes minimal configuration examples:
+    - `.swiftformat` — basic formatting rules used by `swiftformat`/community tools.
+    - `.swiftlint.yml` — basic SwiftLint configuration. These are small defaults; adjust rules to taste.
 
 - **Common CI commands**
   - Build + test (fast): `swift test --enable-test-discovery`

CONTRIBUTING.md

@@ -0,0 +1,46 @@
+Thank you for contributing to SwiftGit — this document explains the recommended workflow, tests, and PR guidance used by automated agents and maintainers.
+
+Quick start
+- Build: `swift build`
+- Run tests (all): `swift test`
+- Run a single test: `swift test --filter <TestName>`
+
+Branching & commits
+- Create a short-lived feature branch: `git checkout -b feat/short-description` or `fix/description`.
+- Keep commits small and focused. Commit messages should explain *why* (1–2 lines).
+- Do not amend pushed commits unless explicitly requested.
+
+Tests
+- Prefer adding unit tests under `Tests/SwiftGitTests/` using existing helpers.
+- Integration tests use an embedded or system `git` and will `XCTSkip` when none is available. Use `envOrSkip()` helpers where appropriate.
+- Run a specific test case by name with `swift test --filter Test.testName`.
+
+Style & lint
+- Follow the conventions in `AGENTS.md` (imports ordering, 4-space indentation, minimal force-unwrapping).
+- This repo includes minimal config files for format/lint: `.swiftformat` and `.swiftlint.yml`.
+- A simple pre-commit example is available at `tools/pre-commit.sh`. To enable it locally, run:
+
+```
+mkdir -p .git/hooks
+cp tools/pre-commit.sh .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+```
+
+  This hook runs `swiftformat` and `swiftlint autocorrect` if those tools are installed. It is optional and not enforced by CI by default.
+
+PR checklist
+- Include a short summary and why the change is needed.
+- Add or update tests for behavior changes.
+- Ensure `swift test` passes locally.
+- Mention any CI requirements or special environment needs (e.g., credential helpers).
+
+CI
+- This repo includes a GitHub Actions workflow at `.github/workflows/ci.yml`.
+- CI runs on macOS and uses the embedded git bundle when appropriate.
+
+Large changes
+- For changes to public APIs, document migration notes and consider a changelog entry.
+- Avoid modifying the embedded git bundle at `Sources/SwiftGit/Resource/git-instance.bundle` unless intentional.
+
+Need help?
+- Open an issue using the templates in `.github/ISSUE_TEMPLATE/`.

Package.swift

@@ -21,6 +21,7 @@ let package = Package(
             resources: [
                 .copy("Resource/git-instance.bundle")
             ]),
+        // Example target removed — no Examples/ directory present in this tree.
         .testTarget(
             name: "SwiftGitTests",
             dependencies: [

README.md

@@ -1,3 +1,141 @@
 # SwiftGit
 
-A description of this package.
+SwiftGit is a Swift Package that wraps and orchestrates Git command-line functionality
+so you can drive Git operations programmatically from Swift. It includes a small
+shell abstraction, typed models for common git results, command builders for many
+git subcommands, and an embedded portable git distribution for environments that
+don't provide `git` on PATH.
+
+This README gives a focused code-oriented overview of the implementation in
+`Sources/` and practical instructions for building, testing, and contributing.
+
+Key features
+- Thin, testable wrappers around `git` commands (clone, commit, push, tag, stash, etc.)
+- Centralized process execution utilities in `Shell` supporting Combine and async/await
+- Typed models for common git outputs (`GitStatus`, `Commit`, `ShowCommitResult`)
+- Embedded portable git at `Sources/SwiftGit/Resource/git-instance.bundle` for hermetic runs
+- Extensive unit and integration tests that exercise parsing and real git workflows
+
+Table of contents
+- Project layout
+- Build & test
+- Important modules (quick code map)
+- Embedded git bundle
+- Tests and integration tests
+- Contribution notes
+ - Contribution notes
+  - See `CONTRIBUTING.md` for contribution workflow, pre-commit hook instructions, and lint/format guidance.
+
+Project layout (sources)
+- `Sources/SwiftGit/` — main package sources
+  - `Custom/` — hand-written implementation
+    - `commands/` — high-level command helpers, e.g. `git-commands-clone.swift`, `git-commands-tag.swift`
+    - `models/` — typed models like `GitStatus.swift`, `Commit.swift`, `Reference.swift`
+    - `results/` — parsing results and helpers (e.g. `ShowCommitResult.swift`)
+    - `Shell.swift` — centralized Process wrapper with Combine + async/await support
+    - `GitEnvironment.swift` — locate and configure embedded or system git
+    - `Git.swift` — top-level `Git` class, wiring environment, shell, and triggers
+    - `Repository.swift` (+ extensions) — repository-level helpers
+  - `Resource/git-instance.bundle/` — portable git binaries and extras included in the package
+  - `options/` — typed option values used to compose command arguments
+
+Build & test
+- Build the package (debug):
+
+```bash
+swift build
+```
+
+- Build for release:
+
+```bash
+swift build -c release
+```
+
+- Run the full test suite:
+
+```bash
+swift test
+```
+
+- Run a single test by name (recommended):
+
+```bash
+# filter matches test case and/or function name
+swift test --filter ParseTests.testChangedEntryIndex_valid
+swift test --filter test_format_date
+```
+
+- Run tests in parallel (CI friendly):
+
+```bash
+swift test --parallel
+```
+
+Important modules (quick code map)
+- `Shell` (`Sources/SwiftGit/Custom/Shell.swift`)
+  - Centralizes process creation, captures stdout/stderr, provides publishers and async helpers.
+  - Use `Git.data(...)` or `Git.run(...)` which delegate to `Shell.Instance`.
+
+- `GitEnvironment` (`Sources/SwiftGit/Custom/GitEnvironment.swift`)
+  - Selects between embedded git (`.embed`), system git (`.system`), or custom folder.
+  - Exposes environment variables used to run git (e.g. `GIT_EXEC_PATH`).
+
+- `Git` (`Sources/SwiftGit/Custom/Git.swift`)
+  - High-level entrypoint. Use `Git(environment:)` or `try Git.shared` (throws if environment fails).
+  - Methods: `run`, `runPublisher`, `data` with variants for arrays of args and string commands.
+
+- `Repository` (`Sources/SwiftGit/Custom/Repository.swift` + `Repository+*.swift`)
+  - Convenience methods that operate in a repository directory (run, clone, status, tag, etc.).
+
+- `GitStatus` and parsing models (`Sources/SwiftGit/Custom/models/GitStatus.swift`)
+  - Strongly-typed representations of `git status` output. Parsing code is defensive to avoid crashes on malformed input.
+
+Embedded git bundle
+- This repository includes a pre-packaged git distribution at:
+
+  `Sources/SwiftGit/Resource/git-instance.bundle`
+
+- `GitEnvironment` will prefer the embedded instance when `Style.embed` is selected or when `Style.auto` finds it.
+- Agents and tests should not modify files under the bundle. Use `GitEnvironment.Style.custom(URL)` to point to an alternate git distribution.
+
+Tests and integration tests
+- Tests live under `Tests/SwiftGitTests/`.
+  - Unit tests: parsing and helpers (safe parsing of `git` output, command splitting).
+  - Integration tests: initialize temporary repos and run real git workflows (init, add, commit, tag, branch, stash, rebase, plumbing commands like `write-tree`).
+- Integration tests try to use the embedded git first and fall back to system git. If neither is available they skip.
+- Helper examples: `Tests/SwiftGitTests/IntegrationTests.swift`, `PlumbingTests.swift`, `ShowCommitResultTests.swift`.
+
+Design & safety notes
+- Parsing: code attempts to be defensive; `GitStatus` uses failable/parsing helpers and falls back to safe defaults for malformed input.
+- Process execution: `Shell` captures stdout/stderr and surfaces a typed error when a process exits non‑zero (includes exit code and working directory where possible).
+- Command string handling: the library provides a `splitCommandLine` helper to handle quoted/escaped arguments for string-based overloads. Prefer array-based overloads when possible to avoid shell-escaping issues.
+
+CI
+- A GitHub Actions workflow is included at `.github/workflows/ci.yml` and runs the build + tests on `macos-latest`.
+
+Contributing and agents
+- There is an `AGENTS.md` file with rules and commands for automated agents and contributors. Agents should follow its guidelines when editing, testing, and committing.
+
+Example usage
+- Simple programmatic example (conceptual):
+
+```swift
+import SwiftGit
+
+// create environment and git
+let env = try GitEnvironment(type: .auto)
+let git = try Git(environment: env)
+
+// run git --version
+let version = try git.run(["--version"])
+print("git version: \(version)")
+```
+
+Where to look next
+- If you want to understand parsing code, start with `Sources/SwiftGit/Custom/results/ShowCommitResult.swift` and
+  `Sources/SwiftGit/Custom/models/GitStatus.swift`.
+- To add a new command helper, follow existing patterns under `Sources/SwiftGit/Custom/commands/`.
+
+Questions or issues
+- Open an issue describing what you tried, including commands and repository state. If you want me to extend tests to cover more commands from the official Git docs, say which areas to prioritize (plumbing, submodule flows, network edge cases, etc.).

Sources/SwiftGit/Custom/Shell.swift

@@ -187,6 +187,29 @@
                 .get()
         }
 
+        @discardableResult
+        public func data(_ args: Shell.Arguments, input: Data?) throws -> Data {
+            var args = args
+            changedArgsBeforeRun?(&args)
+            let process = self.setupProcess(args.exec, args.commands, context: args.context)
+
+            if let input = input {
+                let inputPipe = Pipe()
+                process.standardInput = inputPipe
+                try inputPipe.fileHandleForWriting.write(contentsOf: input)
+                try inputPipe.fileHandleForWriting.close()
+            }
+
+            let output = Shell.Standard(publisher: args.context?.standardOutput).append(
+                to: &process.standardOutput)
+            let error = Shell.Standard(publisher: args.context?.standardError).append(
+                to: &process.standardError)
+            try process.run()
+            process.waitUntilExit()
+            return try result(process, output: output.availableData, error: error.availableData)
+                .get()
+        }
+
         @discardableResult
         public func zshPublisher(_ args: Shell.ShellArguments) -> AnyPublisher<Data, Error> {
             dataPublisher(args.arguments)