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.

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.

---

Installation

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

Requirements

• Python ≥ 3.10
• Git
• GitHub CLI (gh) — 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, then run gh auth login to authenticate.

---

Quick Start

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

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

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

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

# 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 — zero interactive prompts during execution.

---

Configuration

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

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

---

See Also

• CHANGELOG.md — Version history
• ROADMAP.md — What's coming next
• KNOWN_ISSUES.md — Bugs and workarounds