Metadata-Version: 2.4
Name: naissance
Version: 2.0.1
Summary: Git Repository Genesis Utility
License: MIT
Project-URL: Homepage, https://github.com/DODO-unique/Naissance
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Dynamic: license-file

# Naissance

> *A more dramatic Git Repository Genesis Utility.*

Naissance creates both local and remote repositories in one shot. No context switching between terminal and browser — just run one command and your repo is alive.

<!-- ![Naissance Demo](./docs/demo.gif) -->


### Philosophy

Naissance is meant to **get out of the way**. The goal is always to minimize friction between "I want a repo" and "the repo exists." No prompts, no decisions at runtime, no context switching. You type one command, naissance handles the rest, and you're already writing code. Every design choice should serve this principle.

<!-- TODO: Add hero banner/screenshot here -->

---

## Installation

```bash
# Clone and install
git clone https://github.com/DODO-unique/Naissance.git
cd Naissance
pip install .
```

### Requirements 

- Python ≥ 3.10
- [Git](https://git-scm.com/)
- [GitHub CLI (`gh`)](https://cli.github.com/) — authenticated via `gh auth login`

> **Note:** `gh` is a crucial dependency — naissance uses it to create remote repositories. Without it, the tool cannot function. If `gh` is not installed, naissance will detect this at startup and suggest how to install it:
> ```
>   ⨯ GitHub CLI (gh) is not installed or not on PATH
> ```
> Install it from [cli.github.com](https://cli.github.com/), then run `gh auth login` to authenticate.

---

## Quick Start

```bash
# Create a new repo "horizon" in the current directory
naissance horizon

# That's it. Local + remote, done.
```

<!-- TODO: Add terminal recording / screenshot of output here -->
<!-- ![Quick Start Output](./docs/quickstart.png) -->

### What happens

```
┼─────────────────────────────────────────────────────────────┼
|       _   __      _
|      / | / /___ _(_)_____________ _____  ________
|     /  |/ / __ `/ / ___/ ___/ __ `/ __ \/ ___/ _ \
|    / /|  / /_/ / (__  |__  ) /_/ / / / / /__/  __/
|   /_/ |_/\__,_/_/____/____/\__,_/_/ /_/\___/\___/
|                                        v2.0.1
|
|            Git Repository Genesis Utility
┼─────────────────────────────────────────────────────────────┼

  Birthing repository...

  ✓ git found
  ✓ gh authenticated
  ✓ Path resolved: C:\Code\horizon
  ✓ Directory created
  ✓ GitHub repository created (private)
  ✓ Git initialized
  ✓ README.md
  ✓ .gitignore
  ✓ Initial commit
  ✓ Pushed to main

  ✨ horizon is alive.
```

---

## Usage

```bash
naissance <repo_name> [--apath] [--name NAME] [--public]
```

| Flag | Description |
|---|---|
| `repo_name` | Name or path of the repo. Resolved relative to CWD. Use `.` for current directory. |
| `--apath` | Treat `repo_name` as an absolute path |
| `--name NAME` | Override the remote repository name (defaults to directory name) |
| `--public` | Create the remote repo as public (default: private) |
| `-v, --version` | Show version |

### Examples

```bash
# Relative path — creates ./horizon
naissance horizon

# Nested path — creates ./projects/horizon
naissance projects/horizon

# Current directory — uses folder name as repo name
naissance .

# Absolute path
naissance "C:\Code\horizon" --apath

# Different remote name than the directory
naissance horizon --name my-cool-project

# Public repo
naissance horizon --public
```

---

## How It Works

Naissance detects the state of the target directory and adapts:

| State | What naissance does |
|---|---|
| **Doesn't exist** | Creates the directory → `gh repo create --clone` → scaffolds README + .gitignore → commits → pushes |
| **Empty directory** | `git init` → scaffolds → `gh repo create --source` → pushes |
| **Has files, no git** | `git init` → scaffolds → stages all → commits → `gh repo create --source` → pushes |
| **Already git-initialized** | Checks no remote exists → `gh repo create --source` → pushes |

All decisions (visibility, scaffold files, commit message) are driven by [`defaults.yml`](./defaults.yml) — **zero interactive prompts** during execution.

---

## Configuration

Edit `defaults.yml` next to the package to change defaults:

```yaml
version: "2.0.1"
visibility: "private"          # "private" or "public"
create_readme: true
create_gitignore: true
prompt_description: false
default_branch: "main"
initial_commit_message: "initial commit"
```

---

## Error Handling

Naissance never leaks raw tracebacks. All errors are caught and displayed cleanly:

```
  ⨯ git is not installed or not on PATH
  ⨯ GitHub CLI is not authenticated. Run: gh auth login
  ⨯ Remote repository already exists: horizon
  ⨯ Permission denied: C:\Protected\path
```

---

## License

[MIT](./LICENSE)

---

## See Also

- [CHANGELOG.md](./CHANGELOG.md) — Version history
- [ROADMAP.md](./ROADMAP.md) — What's coming next
- [KNOWN_ISSUES.md](./KNOWN_ISSUES.md) — Bugs and workarounds
