TirSystem-BashScript/RepoFoundry
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Describe the files git ignores in the README

Browse Source 
Add the "Git excludes" step to the overview, the sample plan, the numbered
run steps and a new section: which paths are excluded and why, that nothing
is committed or changed in a tracked file, that the entries live in
.git/info/exclude and so are not shared with a clone, what happens to a path
git already tracks, and how to track one anyway. Add the tracked-path case to
the error table and the new roles of git.sh and framework.sh to the code
layout.

Closes #67
This commit is contained in:
Tirsvad
2026-10-08 14:20:03 +08:00
parent c379dd4d75
commit cc157816c7
1 changed files with 47 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+47 -4
View File
@@ -8,7 +8,8 @@ RepoFoundry (`src/create-project.sh`) sets up a new project in one run:
- and a **local project** with one credential-free remote, `origin` (Gitea), and the
[SQA-QC-Framework](https://git.tirsystem.com/TirSystem/SQA-QC-Framework)
added as a git submodule, with its skills, git hooks (and optionally the plan
gate) and templates installed.
gate) and templates installed. The files it installs (`.claude`, `.agents` and
`AGENTS.md`) are excluded from git in the new project.
It is a Bash script. It asks for the repository name, description, visibility
and owner (a user or an organization, separately on each host), shows a plan,
@@ -259,6 +260,7 @@ Plan:
Framework : add ssh://git@git.example.org:10022/Team/SQA-QC-Framework.git as a submodule
Skills and hooks : install once; plan gate no
Templates : AGENTS.md and docs/artifact-registry.md (you are asked before a file is replaced)
Git excludes : /.claude /.agents /AGENTS.md go into .git/info/exclude (no tracked file changes)
```
Without `--apply` that is all that happens. With `--apply` the script asks
@@ -272,7 +274,10 @@ Without `--apply` that is all that happens. With `--apply` the script asks
repository holds the license commit, that history;
5. the framework as the submodule `framework`;
6. the framework's skills and git hooks, and the plan gate if chosen;
7. `AGENTS.md` and `docs/artifact-registry.md` from the framework's templates.
7. `AGENTS.md` and `docs/artifact-registry.md` from the framework's templates;
8. `/.claude`, `/.agents` and `/AGENTS.md` added to the new project's
`.git/info/exclude`, so git does not list them (see
[The files git ignores](#the-files-git-ignores-in-the-new-project)).
No commit is made in the new project. Work on a branch there: the framework's
hooks refuse commits on `main`.
@@ -298,6 +303,39 @@ it replaces an existing `core.hooksPath`, and before it replaces an existing
replaces a remote that points somewhere else, and git itself refuses to
overwrite a file when the license history is checked out.
### The files git ignores in the new project
The framework installs files that are copies, not the project's own work. After
the templates are copied, the script makes git ignore three paths in the new
project by adding them to its `.git/info/exclude`:
| Path | What it is |
| --- | --- |
| `/.claude` | the skills for the standalone Claude Code CLI (the whole folder) |
| `/.agents` | the skills for Codex CLI and other tools that read `.agents/skills` (the whole folder) |
| `/AGENTS.md` | the project instructions, copied from the framework's template |
- **Nothing is committed and no tracked file changes.** `.gitignore` is not
touched, and `framework`, `.gitmodules` and `docs/artifact-registry.md` stay
visible to git: they are part of the project.
- **The entries belong to this clone.** `.git/info/exclude` is never committed
or pushed, so a fresh clone has neither the entries nor these files. There,
run `git submodule update --init --recursive` and then
`bash framework/scripts/install-skills.sh` to make the skills again.
`AGENTS.md` cannot be made again that way: it is a copy of a template that
you edit, so what you add to it exists only in the clone where you wrote it.
- **The whole `.claude` and `.agents` folders are ignored,** not only their
`skills` folders, so anything else you keep there (settings, agents) is
ignored too.
- **A path git already tracks stays tracked,** because an exclusion does not
apply to a tracked file. The script never removes anything from git; the
summary names the path ("git tracks AGENTS.md, so it is not ignored"). Run
`git rm --cached` on it yourself if you want it ignored.
- **Without SSH to Gitea** the framework steps are skipped, and so is this one.
- **To track one of the paths anyway,** delete its line from
`.git/info/exclude` in the project and `git add` it. Running the script again
in that directory adds the line back.
## SSH access to Gitea
The framework submodule is fetched over SSH on port **10022**
@@ -410,6 +448,7 @@ step, `2` a usage error.
| A step fails after another succeeded | stops and prints what exists, what failed and how to continue | fix the cause and run the **same command again with `--apply`**: what was created is offered for reuse |
| The mirror is refused (disabled, interval too short) | keeps the repositories and reports it | change `MIRROR_INTERVAL` or ask the Gitea administrator, then run again |
| The framework submodule cannot be fetched | reports the address and how to test SSH | fix your SSH access, run again |
| Git already tracks `.claude`, `.agents` or `AGENTS.md` in the project | leaves it tracked and names it in the summary; the other paths are excluded | `git rm --cached` it if you want it ignored |
| `sync_on_commit` was ignored by Gitea | warns; the mirror syncs on its interval | enable it in the repository settings if needed |
A partial run is reported like this:
@@ -453,6 +492,10 @@ web interface and the project directory by hand.
copy.
- **The framework needs SSH.** Without SSH access to Gitea the framework steps
can only be skipped.
- **The ignored framework files are not shared.** `.claude`, `.agents` and
`AGENTS.md` are excluded in the clone the script made, not in the repository,
so another clone does not have them (see
[The files git ignores](#the-files-git-ignores-in-the-new-project)).
- **Tested on Windows (Git Bash) only so far.** Running the tests on Linux and
macOS is an open follow-up.
@@ -484,9 +527,9 @@ file. The files are loaded from that directory only, by a fixed path.
| `plan.sh` | printing what the script is about to do |
| `repositories.sh` | creating the GitHub and Gitea repositories |
| `mirror.sh` | the Gitea to GitHub push mirror |
| `git.sh` | running git for the new project without prompts or tokens on a command line |
| `git.sh` | running git for the new project without prompts or tokens on a command line, and adding entries to its `.git/info/exclude` |
| `localproject.sh` | the local directory, git repository and remotes |
| `framework.sh` | the framework submodule, skills, hooks and templates |
| `framework.sh` | the framework submodule, skills, hooks and templates, and the git excludes for the files it installs |
| `apply.sh` | confirmations and the apply flow; the only code that changes anything |
| `cli.sh` | usage text and option parsing |