codespace/gen.README.md.sh at master · kiprasmel/codespace · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
#!/usr/bin/env bash

NEW="README.new.md"
CURR="README.md"

export HELP_CODESPACE_CMD_OUTPUT="$(./codespace -h)"
export HELP_CODESPACE_STACK_CMD_OUTPUT="$(./codespace stack -h)"

#shellcheck disable=SC2016
cat <<'EOF' | envsubst '$HELP_CODESPACE_CMD_OUTPUT $HELP_CODESPACE_STACK_CMD_OUTPUT' > "$NEW"
# codespace

git worktrees, with convenience.

<!--
NOTE: THIS FILE IS AUTO-GENERATED. DO NOT EDIT MANUALLY.

EDIT gen.README.md.sh instead.
-->

## features

- post-create scripts
  - install dependencies, link files, etc
- simple setup for storing files outside main repository (e.g. AGENTS.md with your preferences)
  - while still tracking in git, just in a separate repo

## use-cases

- working on multiple features at the same time
- reviewing PRs locally
- running multiple agents in parallel on the same task, comparing output, picking best results
- fast iteration in feature-based development
  - customizable pre-defined stacks of repositories to create codespaces from
  - work in parallel on different features
  - shared context for agents - access to all repos involving a feature
- ...

## setup

by default, will install to `$HOME/.local/bin/`:

```sh
./install.sh
```

or, custom prefix (results in `/usr/local/bin/`):

```sh
PREFIX="/usr/local" ./install.sh
```

#### recommended aliases

```sh
git config --global alias.cs "\!codespace"
git config --global alias.css "\!codespace stack"
```

## usage

### codespace

```console
$ codespace -h

$HELP_CODESPACE_CMD_OUTPUT
```

### codespace stack

```console
$ codespace stack -h

$HELP_CODESPACE_STACK_CMD_OUTPUT
```

## testing

bats-based test suite covering config resolution & post-create behavior.

```sh
./test/setup.sh   # one-time: vendor bats-core + helpers into test/vendor/
./test/run.sh     # run all tests; forwards args to bats
```

#### sample stacks.json

```json
{
    "version": "0",
    "stacks": {
    	"default": [
            { "name": "frontend", "cloneURL": "git@github.com:kiprasmel/frontend.git" }
            { "name": "backend", "cloneURL": "git@github.com:kiprasmel/backend.git" },
    	],
        "all": [
            { "name": "admin", "cloneURL": "git@github.com:kiprasmel/admin.git" },
            { "name": "backend", "cloneURL": "git@github.com:kiprasmel/backend.git" },
            { "name": "frontend", "cloneURL": "git@github.com:kiprasmel/frontend.git" },
            { "name": "infra", "cloneURL": "git@github.com:kiprasmel/infra.git" },
            { "name": "mobile", "cloneURL": "git@github.com:kiprasmel/mobile.git" }
        ],
        "fe": [
            { "name": "frontend", "cloneURL": "git@github.com:kiprasmel/frontend.git" }
        ],
        "be": [
            { "name": "backend", "cloneURL": "git@github.com:kiprasmel/backend.git" }
        ]
    }
}
```

EOF

test -n "$GIT_PAGER" && {
	diff -u "$CURR" "$NEW" | $GIT_PAGER
	DIFF_EXIT=$?
} || {
	diff -u "$CURR" "$NEW"
	DIFF_EXIT=$?
}

if [ $DIFF_EXIT -ne 0 ]; then
	>&2 echo "no diff"
	rm "$NEW"
else
	mv -f "$NEW" "$CURR"
fi