git-deploy-ng 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9bac8c7043b8147444e762d919dbc943862b999a420b26112edcf8e893fb509
-  data.tar.gz: 00e10711fdcdafc3fc8a473f273f051d0eb09b9ee9c84c9db3796c4d1ee71abf
+  metadata.gz: 0b64c184c2caea92356620a38fe3f61b1127a57db6f07c685e0fdd7e631013aa
+  data.tar.gz: 352f0a909af1721966f5205be7fab6cb884e7dad8f5673f4242232bcd351ca26
 SHA512:
-  metadata.gz: aa0e71d63684c7e958e90b118cb3cfe18fce10ec21993a8d84e307e9f74ba806a632647554bdea917e502b24089b5faa59029820e14a36eb8cd31b4c9abdcca4
-  data.tar.gz: f81335e3f58ff15a32d7b335acb888df020b7a139dfbaa24ea8cec5c2027c54789ddb201b634f160062f4eb21e189a7a37cde5858454c35390c40d424258653d
+  metadata.gz: 3b358f7015854510c0fd1d17fc65f7faa2b9564fc5fccc7a3dd7ce160cf28193b4c510e40a9f0e68650f83fe95e7e7542e859d4859b4bac6b028165708b92d85
+  data.tar.gz: fed8047e5dc0ca7df1594139515bf1a06d39ae1663fe740b0882eb01c0c3c1676c55754884051a69fe25e1fff211ab147a93619274700092fdbd2fc4180ed329

data/AGENTS.md

@@ -0,0 +1,46 @@
+# AGENTS.md
+
+Terse context for AI coding agents working in this repo.
+
+## Project
+
+**git-deploy-ng** — Ruby gem, CLI `git deploy`. Push-based deploy over SSH (Thor + net-ssh). Community fork of mislav/git-deploy. v0.8.x stayed compatible with upstream 0.7.0; **v0.9.0** has minor CLI changes (see `CONTRIBUTING.md`). Servers only need bash/git.
+
+## Layout
+
+```
+bin/git-deploy              # CLI entry
+lib/git_deploy.rb           # Thor commands
+lib/git_deploy/             # configuration, SSH, generator
+lib/hooks/post-receive.sh   # installed on server at setup
+lib/git_deploy/templates/   # init callback templates (per stack)
+spec/                       # RSpec — integration-style, public interfaces
+```
+
+## Conventions
+
+- **Tests:** `bundle exec rspec`. Add/update specs for behaviour changes. Prefer integration tests through CLI/generator/public APIs, not implementation details.
+- **Compat:** Don't break existing `deploy/` callbacks or CLI without explicit issue discussion. Hook behaviour changes are opt-in via `git deploy hooks`.
+- **Scope:** Minimal diffs. Match existing style (Thor options, module mixins, shell hooks).
+- **Commits:** Conventional commits (`feat:`, `fix:`, `docs:`, `ci:`). Don't commit unless asked.
+- **Git:** No force push, no destructive git ops without explicit user request.
+
+## Key behaviour
+
+- Remote commands require `-r <remote>` (v0.9+).
+- `deploy_to` parsed from git remote URL; relative scp paths resolve against remote `$HOME`.
+- `Generator` (Thor::Group) writes `deploy/*` from template dir on `git deploy init`.
+- SSH via `Net::SSH` / `Net::SCP`; ed25519 needs optional `ed25519` + `bcrypt_pbkdf` gems.
+
+## Release
+
+- Gem: `git-deploy-ng` (not `git-deploy`).
+- Version in `git-deploy-ng.gemspec`. Update `CHANGELOG.md` with `bin/update-changelog` before tagging.
+- Tag `vX.Y.Z` triggers RubyGems publish (needs `RUBYGEMS_API_KEY` secret).
+- CI: `.github/workflows/ci.yml` (matrix test + gem build), `release.yml` (tag publish + GitHub Release).
+
+## Docs
+
+- User-facing: `README.md`
+- Contributors: `CONTRIBUTING.md`
+- Planning: `ROADMAP.md`, local `tmp/` (gitignored)

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.9.0] - 2026-07-04
+
+### Added
+- Add framework templates for init including PHP/composer
+- Add git deploy download for pulling files from the server
+- Auto-update CHANGELOG on release
+
+### Changed
+- Add README.md and AGENTS.md, retire README.markdown
+
+### Fixed
+- Require remote and guard setup against destructive overwrites
+- Resolve relative scp-style remote paths against remote $HOME
+- Warn on init when deploy path collides with existing files
+
+
+## [0.8.0] - 2026-06-10
+
+### Added
+
+- Ruby 3.x and 4.x compatibility; dynamic default branch detection
+- Publish as `git-deploy-ng` on RubyGems
+- GitHub Actions CI (Ruby 2.7–4.0) and gem build verification
+- Clear error when ed25519 SSH gems are missing
+
+### Changed
+
+- Dependency upgrades (Thor, net-ssh, net-scp)

data/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-Thank you for contributing to git-deploy-ng. This project is a backwards-compatible continuation of [mislav/git-deploy](https://github.com/mislav/git-deploy).
+Thank you for contributing to git-deploy-ng. This project continues [mislav/git-deploy](https://github.com/mislav/git-deploy) — v0.8.x preserved upstream compatibility; v0.9.0 introduces minor CLI changes (see [Backwards compatibility](#backwards-compatibility)).
 
 ## Getting started
 
@@ -20,15 +20,53 @@ bundle exec rspec
 
 ## Backwards compatibility
 
-v0.8.x must not break existing users migrating from upstream 0.7.0:
+### v0.8.x
+
+Must not break existing users migrating from upstream 0.7.0:
 
 - Same `git deploy` subcommands and flags
 - Same default `post-receive` hook behaviour (improvements are opt-in via `git deploy hooks`)
 - Existing `deploy/` callback scripts in deployed apps should keep working unchanged
 
+### v0.9.0
+
+Minor intentional compatibility changes — called out in release notes. **Existing `deploy/*` callbacks in deployed apps stay unchanged.**
+
+| Change | Notes |
+|--------|-------|
+| Required `-r` on remote commands | No default remote (was `origin` in older docs) |
+| Setup safety | `setup` requires explicit remote; `--force` to overwrite hooks |
+| Init collision guard | Warn when `deploy/` non-empty; abort if `deploy` is a file |
+| Relative remote paths | SCP-style paths without leading `/` resolve against remote `$HOME` |
+| New commands / flags | `download`, `init --template` |
+
+See [ROADMAP.md](ROADMAP.md#v090-in-progress) for scope.
+
 ## Releases
 
-Releases are tagged (`v0.8.0`, etc.) and published to RubyGems as `git-deploy-ng`. Maintainers cut releases from `master` after CI passes.
+Releases are published to [RubyGems](https://rubygems.org/gems/git-deploy-ng) as `git-deploy-ng` via GitHub Actions when a version tag is pushed.
+
+### Cutting a release
+
+1. Bump `gem.version` in `git-deploy-ng.gemspec` on `master` and merge.
+2. Update the changelog from conventional commits since the last tag:
+
+    ```bash
+    ruby bin/update-changelog
+    git add CHANGELOG.md git-deploy-ng.gemspec
+    git commit -m "chore: prepare release X.Y.Z"
+    ```
+
+3. Ensure CI is green on `master`.
+4. Tag the release commit (tag must match the gemspec version):
+
+    ```bash
+    git tag v0.9.0
+    git push origin master
+    git push origin v0.9.0
+    ```
+
+5. The **Release** workflow verifies the changelog, creates a GitHub Release, and publishes to RubyGems.
 
 ## Internal planning
 

data/README.md

@@ -0,0 +1,335 @@
+# git-deploy-ng
+
+Push-based deployment over SSH — a community continuation of [mislav/git-deploy](https://github.com/mislav/git-deploy), published on RubyGems as **git-deploy-ng**.
+
+Deploy with a single git push:
+
+```sh
+git push production main
+```
+
+Only the person setting up deployment needs the gem on their machine. Production servers need **bash and git only** — no Ruby on the server.
+
+- **CLI:** Same commands as upstream; **v0.9.0** introduces minor compatibility changes — see [Backwards compatibility](CONTRIBUTING.md#backwards-compatibility) and [ROADMAP.md](ROADMAP.md#v090-in-progress)
+- **Ruby:** 2.7+ on the setup machine (including 4.x)
+- **Auth:** SSH public keys (password auth not supported)
+
+See also: [ROADMAP.md](ROADMAP.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [AGENTS.md](AGENTS.md)
+
+---
+
+## Table of contents
+
+- [How it works](#how-it-works)
+- [Installation](#installation)
+- [Initial setup](#initial-setup)
+- [Everyday deployments](#everyday-deployments)
+- [Init templates](#init-templates)
+- [Deploy callbacks](#deploy-callbacks)
+- [CLI reference](#cli-reference)
+- [Remote URL formats](#remote-url-formats)
+- [Restart recipes](#restart-recipes)
+- [Multiple environments](#multiple-environments)
+- [Migrating from mislav/git-deploy](#migrating-from-mislavgit-deploy)
+- [Which git-deploy?](#which-git-deploy)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+
+---
+
+## How it works
+
+```
+Developer machine                         Production server
+─────────────────                         ─────────────────
+git remote add production user@host:/app
+git deploy setup -r production     ──SSH──►  mkdir /app, git init, install post-receive hook
+git deploy init                    ──local►  generate deploy/* callbacks in your repo
+git push production main           ──git──►  post-receive hook runs deploy/after_push
+```
+
+1. **`git deploy setup`** creates (or reuses) a git repository on the server and installs a `post-receive` hook.
+2. **`git deploy init`** generates `deploy/` callback scripts in your application repo — commit these.
+3. **`git push production <branch>`** updates the server working copy and runs callbacks.
+
+The hook checks out the pushed branch, then executes scripts in `deploy/`. Output is appended to `log/deploy.log` on the server.
+
+---
+
+## Installation
+
+```sh
+gem install git-deploy-ng
+```
+
+Do **not** add it to your app's Gemfile. One developer runs setup once per project/host.
+
+---
+
+## Initial setup
+
+### 1. Add a deploy remote
+
+The remote name is arbitrary (`production`, `staging`, `online`, …):
+
+```sh
+git remote add production "user@example.com:/apps/mynewapp"
+```
+
+Use an **absolute** path (`/apps/...`) or a **home-relative** path (`apps/mynewapp` → `$HOME/apps/mynewapp`). See [Remote URL formats](#remote-url-formats).
+
+### 2. Set up the server repository
+
+```sh
+git deploy setup -r production
+```
+
+This will:
+
+- Create the deploy directory if missing
+- Run `git init` (skipped if `.git` already exists)
+- Install `post-receive` from `lib/hooks/post-receive.sh`
+- Configure the remote HEAD to match your **current local branch** (`main` or `master`)
+
+Options:
+
+| Flag | Purpose |
+|------|---------|
+| `-r production` | **Required** — git remote name (no default) |
+| `--force` / `-f` | Overwrite an existing `post-receive` hook |
+| `--shared` / `-g` | Shared repository (`git init --shared`) |
+| `--sudo` / `-s` | Create deploy dir with sudo |
+
+### 3. Generate deploy callbacks
+
+```sh
+git deploy init --template rails-passenger
+```
+
+Commit the generated `deploy/` directory. Scripts run on the server during each deploy.
+
+### 4. Push
+
+```sh
+git push production main
+```
+
+### 5. One-time server admin
+
+On the server, configure your web server (nginx/Apache), database, environment variables, etc.
+
+---
+
+## Everyday deployments
+
+```sh
+git push production main
+```
+
+Push the branch that is checked out on the remote (configured during `setup`). Teammates deploy with plain `git push` — they do not need the gem installed.
+
+### What the default Rails template does
+
+On each deploy, `deploy/after_push` typically:
+
+1. Syncs git submodules
+2. Runs `deploy/before_restart` (bundle install, migrations, asset precompile)
+3. Runs `deploy/restart` (app server restart)
+4. Runs `deploy/after_restart` (if present)
+
+Customize everything by editing `deploy/*` in your repo.
+
+---
+
+## Init templates
+
+```sh
+git deploy init --template <name>
+```
+
+| Template | Stack | Generated restart |
+|----------|-------|-------------------|
+| `rails-passenger` | Rails + Passenger | `touch tmp/restart.txt` |
+| `rails-puma` | Rails + Puma | `pumactl restart` (with Passenger fallback) |
+| `php-composer` | PHP + Composer | PHP-FPM reload via systemd |
+| `generic` | Any | No-op — edit manually |
+
+`rails-passenger` is the default. Templates only affect **new** `git deploy init` runs; existing `deploy/` scripts are never overwritten unless files are missing.
+
+If `./deploy` exists as a **file** (not a directory), `init` aborts with an error. If `deploy/` is non-empty, existing files are preserved.
+
+---
+
+## Deploy callbacks
+
+All scripts live in `deploy/` at the repo root. They are ordinary executables (shell, Ruby, anything). All are optional.
+
+| Script | When it runs |
+|--------|--------------|
+| `deploy/setup` | First push to a new branch |
+| `deploy/after_push` | Every subsequent push |
+| `deploy/before_restart` | Called from `after_push` |
+| `deploy/restart` | Called from `after_push` |
+| `deploy/after_restart` | Called from `after_push` |
+| `deploy/rollback` | `git deploy rollback` (instead of `after_push`) |
+
+Hook entry point: `lib/hooks/post-receive.sh` (installed to `.git/hooks/post-receive` on the server).
+
+---
+
+## CLI reference
+
+All commands that connect to a server **require** `-r <remote>`. There is no default remote.
+
+Global options:
+
+| Option | Description |
+|--------|-------------|
+| `-r`, `--remote` | Git remote name (**required** for remote commands) |
+| `-n`, `--noop` | Print commands without executing |
+
+| Command | Description |
+|---------|-------------|
+| `git deploy init [--template NAME]` | Generate `deploy/` callbacks locally |
+| `git deploy setup -r REMOTE [--force]` | Create remote repo + install hook |
+| `git deploy hooks -r REMOTE [--force]` | Refresh remote hook only |
+| `git deploy log -r REMOTE [-l N] [-t]` | Tail deploy log (`-t` to follow) |
+| `git deploy rerun -r REMOTE` | Re-run `after_push` on server |
+| `git deploy restart -r REMOTE` | Run `deploy/restart` on server |
+| `git deploy rollback -r REMOTE` | Reset to previous revision + callback |
+| `git deploy upload -r REMOTE <files…>` | SCP local → server app dir |
+| `git deploy download -r REMOTE <paths…>` | SCP server app dir → local |
+
+---
+
+## Remote URL formats
+
+| Remote | Deploy path |
+|--------|-------------|
+| `user@host:/var/www/app` | `/var/www/app` (absolute) |
+| `user@host:~/apps/app` | `~/apps/app` (home-relative) |
+| `user@host:apps/app` | `$HOME/apps/app` (relative to remote `$HOME`) |
+| `ssh://user@host:2222/path` | `/path` on port 2222 |
+
+GitHub remotes are rejected — you cannot deploy to github.com.
+
+---
+
+## Restart recipes
+
+Match `deploy/restart` to your app server:
+
+**Passenger** (default template):
+
+```sh
+touch tmp/restart.txt
+```
+
+**Unicorn:**
+
+```sh
+kill -USR2 $(cat tmp/pids/unicorn.pid)
+```
+
+**Puma** — use `--template rails-puma`, or:
+
+```sh
+bundle exec pumactl -P tmp/pids/puma.pid restart
+```
+
+**PHP-FPM** — use `--template php-composer`, or:
+
+```sh
+sudo systemctl reload php-fpm
+```
+
+---
+
+## Multiple environments
+
+Use separate git remotes pointing at separate directories on the same (or different) host:
+
+```sh
+git remote add staging  user@server:~/apps/myapp-staging
+git remote add production user@server:~/apps/myapp-production
+
+git deploy setup -r staging
+git deploy setup -r production
+
+git push staging develop
+git push production main
+```
+
+Same `deploy/` scripts usually work for both; set `RAILS_ENV` or equivalent in server environment or in the scripts.
+
+---
+
+## Migrating from mislav/git-deploy
+
+1. `gem uninstall git-deploy` (optional)
+2. `gem install git-deploy-ng`
+3. `git deploy hooks -r production` on each host
+
+Existing `deploy/` scripts in your apps do not need to change. After upgrading, refresh hooks on each host to pick up improvements.
+
+**v0.9.0 compatibility changes:** Minor CLI changes (notably `-r` required on all remote commands). Full list: [CONTRIBUTING.md § Backwards compatibility](CONTRIBUTING.md#backwards-compatibility), [ROADMAP.md § v0.9.0](ROADMAP.md#v090-in-progress).
+
+---
+
+## Which git-deploy?
+
+| Project | Model | Use when |
+|---------|-------|----------|
+| **git-deploy-ng** (this repo) | Push-based: `git push production main` | Heroku-style simplicity, modern Ruby |
+| [mislav/git-deploy](https://github.com/mislav/git-deploy) | Original gem (archived ~0.7.0) | Legacy reference |
+| [git-deploy/git-deploy](https://github.com/git-deploy/git-deploy) | Pull-based: `git deploy start/sync/finish` on a deploy host | Locking, deploy tags, multi-server sync from a staging machine |
+
+---
+
+## Troubleshooting
+
+### `bundle` or `ruby` not found on push (but `git deploy rerun` works)
+
+`git push` runs hooks in a non-interactive shell that may not load `.bashrc`. This is usually a **server environment** issue:
+
+1. Initialize rbenv/rvm/nvm in `~/.profile` or `~/.bash_profile`, not only `.bashrc`.
+2. Or add `deploy/env` on the server with PATH exports (sourced by the hook when present).
+
+### SSH key authentication
+
+Set up key auth with `ssh-copy-id` before running setup. Password auth is not supported.
+
+### `unsupported key type ssh-ed25519`
+
+```sh
+gem install ed25519 bcrypt_pbkdf
+```
+
+git-deploy-ng prints this hint automatically when the gems are missing.
+
+### Setup refuses to overwrite hooks
+
+Use `--force` when re-running setup or hooks on an existing deployment:
+
+```sh
+git deploy setup -r production --force
+```
+
+---
+
+## Development
+
+```sh
+git clone https://github.com/npfedwards/git-deploy.git
+cd git-deploy
+bundle install
+bundle exec rspec
+```
+
+CI runs on Ubuntu and macOS against Ruby 2.7–4.0. Releases publish to RubyGems when a `v*` tag is pushed — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE). Originally by [Mislav Marohnić](https://github.com/mislav); maintained by [Nathan Edwards](https://github.com/npfedwards).

data/ROADMAP.md

@@ -2,9 +2,7 @@
 
 Tracking for git-deploy-ng. **Nothing listed here is a commitment** — items may be reprioritised, dropped, or implemented differently. Any change that affects default behaviour will be called out explicitly in release notes.
 
-## v0.8.0 (in progress)
-
-Scoped fixes for this release:
+## v0.8.0 (released)
 
 | Fix | Upstream context |
 |-----|------------------|
@@ -14,6 +12,20 @@ Scoped fixes for this release:
 | Modern CI (GitHub Actions, Ruby 2.7–4.0) | Travis CI retired |
 | Publish as `git-deploy-ng` on RubyGems | Avoids namespace conflict with upstream gem |
 
+## v0.9.0 (in progress)
+
+Minor CLI compatibility changes from v0.8.x. **Deployed `deploy/*` callbacks are unchanged** — see [CONTRIBUTING.md § Backwards compatibility](CONTRIBUTING.md#backwards-compatibility).
+
+| Change | Issue / PR |
+|--------|------------|
+| Required `-r` on remote commands | [#78](https://github.com/mislav/git-deploy/issues/78) |
+| Setup safety (`--force` for hook overwrite) | [#78](https://github.com/mislav/git-deploy/issues/78) |
+| Init collision warning | [#56](https://github.com/mislav/git-deploy/issues/56) |
+| Relative remote path resolution | [#57](https://github.com/mislav/git-deploy/issues/57) |
+| Framework init templates (`--template`) | [#4](https://github.com/npfedwards/git-deploy/issues/4), [#92](https://github.com/mislav/git-deploy/issues/92) |
+| `git deploy download` | [#83](https://github.com/mislav/git-deploy/issues/83) |
+| README + AGENTS docs | [#53](https://github.com/mislav/git-deploy/issues/53) |
+
 ## Ideas under consideration (post-v0.8.0)
 
 Sourced from upstream open issues and community discussion. If something here interests you, open an issue — priorities are not fixed.

data/bin/update-changelog

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+require_relative '../lib/git_deploy/changelog'
+
+def usage
+  warn <<~USAGE
+    Usage: update-changelog [VERSION] [options]
+
+    Append a version section to CHANGELOG.md from conventional commits since the
+    latest tag. VERSION defaults to git-deploy-ng.gemspec.
+
+    Options:
+      --date YYYY-MM-DD   Release date (default: today)
+      --since REF         Git ref to start from (default: latest tag)
+      --check             Verify CHANGELOG.md documents VERSION and exit
+  USAGE
+  exit 1
+end
+
+args = ARGV.dup
+version = args.shift if args.first&.match?(/\A\d+\.\d+\.\d+\z/)
+
+date = Date.today.iso8601
+since_ref = GitDeploy::Changelog.latest_tag
+check = false
+path = 'CHANGELOG.md'
+
+while (arg = args.shift)
+  case arg
+  when '--help', '-h' then usage
+  when '--check' then check = true
+  when '--date' then date = args.shift || usage
+  when '--since' then since_ref = args.shift || usage
+  else usage
+  end
+end
+
+version ||= GitDeploy::Changelog.gemspec_version
+
+if check
+  content = File.read(path)
+  GitDeploy::Changelog.verify_version!(content, version)
+  puts "CHANGELOG.md documents version #{version}"
+else
+  GitDeploy::Changelog.update_file(path, version, date: date, since_ref: since_ref)
+  puts "Updated #{path} for version #{version}"
+end