新建仓库的前十分钟,最容易埋雷新开一个项目,前十分钟干的事,你闭着眼都能背出来。建src,建tests,从上一个项目里翻出.gitignore复制过来,心想差不多够用了,然后开始写代码。雷就是在这十分钟里埋下的。雷一:.gitignore 是抄来的抄来的.gitignore是上一个项目的。上一个项目是 Python,这一个加了前端;上一个没有 sqlite,这一个有。于是node_modules没被忽略,db/app.sqlite也没被忽略。你在git status里看到一长串文件,顺手git add .,数据库就进了历史。等发现的时候,删文件已经没用了,历史里还在。真要清,得改写历史,然后通知所有人重新 clone。雷二:切个分支,数据没了数据目录没被忽略,或者忽略得不彻底,会发生一件很烦的事:你在feature-x分支上跑了一天,产出的文件被 git 当成了普通文件。切回main,它们被删了,或者被另一个分支的版本覆盖了。运行时产生的东西,就不该让 git 碰。雷三:换一个人接手,谁也找不到东西配置放在哪?config/、conf/、settings/,还是根目录一个.env?数据库文件在哪?上传的文件呢?日志呢?每个项目一个样,写代码的人记得住,可做备份的、做运维的人记不住。他们只能一个个去问,或者翻代码。备份漏了一个目录,往往要等到出事才知道。开源项目stdlayout:每个项目从第一天起,就有同一套目录和 .gitignorestdlayout是一个开源项目。就为了解决上述痛点。它其实就是一个Python文件。这个脚本干的就是这件事stdlayout 的Python 文件,叫init_project.py。你直接下载下来复制到项目根目录,运行:python3 init_project.py它做三件事。第一,建一套固定的目录,所有项目都一样。要提交的:deploy/(部署和健康检查脚本)、config-ops-template/(配置模板,只放占位值)、data-ops/(一个sources.yaml,写明数据在哪)、tests/、manual-tests/、third-party/、reference-data/。不提交的:config-ops/(真实配置和密钥)、data/、db/、upload/、logs/、tmp/、private-docs/。真实配置永远在一个被忽略的目录里,模板永远在一个不会被忽略的目录里,不用靠记性。做备份的人也只需要看data-ops/sources.yaml,就知道该备份什么。第二,补全 .gitignore,覆盖三十多种语言。Python、Node/TypeScript、Rust、Go、Java/Kotlin、C/C、Swift、C#/VB.NET/.NET、Visual Studio、Android、Flutter/Dart、CUDA、ActionScript、Julia、Ada、Fortran、Haskell、Lua、OCaml、Perl、Qt、R、Ruby、Delphi一共 32 个可选的语言段。你的项目只用其中两三种,就加--lang python go,不会塞进一堆用不上的规则。默认全部选上能让你放心在项目中使用不同的语言做开发。不该被git管理的各类生成物都不会被误提交到git上。脚本写的内容都包在一对BEGIN/END注释里。你自己写的规则在块外面,它不会碰;你已经有的规则,它不会重复加。package-lock.json、Cargo.lock、go.sum这类锁文件,它故意不忽略,因为你需要提交它们。第三,跑完之后自己检查。它会用git check-ignore实际问一遍 git:config-ops/到底有没有被忽略?deploy/会不会被误伤?被忽略的目录下有没有文件已经被跟踪了?任何一项不对,退出码是 1,放进 CI 就能拦住。它不会做的它不会覆盖你已有的文件,运行两遍,第二遍什么都不改。它也不会在不是 git 仓库顶层的目录里乱动手:你要是把脚本复制错了地方,它会告诉你,然后退出。想让它顺便git init,加--git-init。想反悔,--undo能撤销脚本生成的东西,但只撤销你没改过的;先加--dry-run看一眼。项目已经有自己的目录结构了,不想要我们的目录,只想要这份 .gitignore?用--gitignore-only,它只写那一块,别的什么都不建。完整的命令行参数推荐你直接复制到你的目录下不添加参数直接执行python3 init_project.py即可。如果你的需求比较复杂请参考下面完整的命令行参数。完整的--help下面是python3 init_project.py --help的完整输出(命令行输出只有英文),每一处后面附了中文对照翻译。$ ./init_project.py --help usage: init_project.py [-h] [--data [DIR ...]] [--lang [LANG ...]] [--docs {auto,yes,no}] [--name-prefix P] [--no-deploy] [--no-config] [--no-third-party] [--no-reference-data] [--no-manual-tests] [--no-tests] [--no-data-ops] [--gitignore-only] [--git-init] [--undo] [--dry-run] [--version] [path] stdlayout: complete a projects standard directories, .gitignore and structure docs. positional arguments: path project directory (default: the directory of this script, so copying it into the project root just works) options: -h, --help show this help message and exit --data [DIR ...] extra data directories (created and gitignored) --lang [LANG ...] only add ignores for these languages: python node typescript rust go java kotlin c cpp swift csharp vb fsharp dotnet visualstudio android flutter dart cuda actionscript julia ada fortran haskell lua ocaml perl qt r ruby delphi pascal (default: all) --docs {auto,yes,no} generate the structure docs (English Chinese). auto only when the project has no files yet --name-prefix P expected repo-name prefix; only warns on mismatch (e.g. 5) --no-deploy do not create deploy/ --no-config do not create config-ops-template/ --no-third-party do not create third-party/ --no-reference-data do not create reference-data/ --no-manual-tests do not create manual-tests/ --no-tests do not create tests/ --no-data-ops do not create>对照翻译用法:init_project.py [-h] [--data [DIR ...]] [--lang [LANG ...]] [--docs {auto,yes,no}] [--name-prefix P] [--no-deploy] [--no-config] [--no-third-party] [--no-reference-data] [--no-manual-tests] [--no-tests] [--no-data-ops] [--gitignore-only] [--git-init] [--undo] [--dry-run] [--version] [path]stdlayout:补全项目的标准目录、.gitignore 和结构说明文档。位置参数参数含义path项目目录(默认:本脚本所在的目录,所以把脚本复制到项目根目录就能直接用)选项选项含义-h, --help显示帮助信息并退出--data [DIR ...]额外的数据目录(会被创建,并加入 gitignore)--lang [LANG ...]只为这些语言添加忽略规则:python node typescript rust go java kotlin c cpp swift csharp vb fsharp dotnet visualstudio android flutter dart cuda actionscript julia ada fortran haskell lua ocaml perl qt r ruby delphi pascal(默认:全部)--docs {auto,yes,no}生成结构说明文档(英文 中文)。auto 仅当项目下还没有文件时才生成--name-prefix P期望的仓库名前缀;不匹配时只提示、不报错(例如 5)--no-deploy不创建deploy/--no-config不创建config-ops-template/--no-third-party不创建third-party/--no-reference-data不创建reference-data/--no-manual-tests不创建manual-tests/--no-tests不创建tests/--no-data-ops不创建data-ops/sources.yaml--gitignore-only只在.gitignore里创建 stdlayout 块(适合有自己目录结构的项目):不建目录,也不生成其他文件;如果该块已经存在,.gitignore保持不动--git-init如果目录还不是 git 仓库,先执行git init,再做其余的事--undo撤销本脚本生成的内容,但只撤销你没改过的(未修改的文件、空目录、.gitignore里的 stdlayout 块);可与--dry-run一起用来预览--dry-run显示会做什么,不改动任何东西--version显示程序版本号并退出stdlayout:补全项目的标准目录、.gitignore 和结构说明文档。只用标准库。可以放心重复运行:绝不覆盖文件,只追加缺少的.gitignore行。python3 init_project.py # 复制到项目根目录后运行 python3 init_project.py /path/to/project # 指定另一个目录 python3 init_project.py --data cache models # 额外的数据目录(创建并忽略) python3 init_project.py --lang python go # 限定语言的忽略规则(默认:全部) python3 init_project.py --gitignore-only # 只写 .gitignore 块;不建目录,不生成其他文件 python3 init_project.py --git-init # 还不是 git 仓库?先 git init,再做其余的事 python3 init_project.py --undo # 撤销它生成的内容,但只撤销你没改过的 python3 init_project.py --dry-run # 显示它会做什么,不改动任何东西 python3 init_project.py --version # 打印版本号没有--git-init时,不是 git 仓库的目录会原样保留、什么都不动(你可能把脚本复制错了地方)。它做什么、为什么这样做:https://github.com/performai-org/stdlayout/blob/main/docs/PROJECT_STRUCTURE.mdhttps://github.com/performai-org/stdlayout/blob/main/docs/PROJECT_STRUCTURE.zh-CN.md(中文)想看看源码和中英文文档都在这里,MIT 协议:https://github.com/performai-org/stdlayout
新建仓库的前十分钟,最容易埋雷新开一个项目,前十分钟干的事,你闭着眼都能背出来。建src,建tests,从上一个项目里翻出.gitignore复制过来,心想差不多够用了,然后开始写代码。雷就是在这十分钟里埋下的。雷一:.gitignore 是抄来的抄来的.gitignore是上一个项目的。上一个项目是 Python,这一个加了前端;上一个没有 sqlite,这一个有。于是node_modules没被忽略,db/app.sqlite也没被忽略。你在git status里看到一长串文件,顺手git add .,数据库就进了历史。等发现的时候,删文件已经没用了,历史里还在。真要清,得改写历史,然后通知所有人重新 clone。雷二:切个分支,数据没了数据目录没被忽略,或者忽略得不彻底,会发生一件很烦的事:你在feature-x分支上跑了一天,产出的文件被 git 当成了普通文件。切回main,它们被删了,或者被另一个分支的版本覆盖了。运行时产生的东西,就不该让 git 碰。雷三:换一个人接手,谁也找不到东西配置放在哪?config/、conf/、settings/,还是根目录一个.env?数据库文件在哪?上传的文件呢?日志呢?每个项目一个样,写代码的人记得住,可做备份的、做运维的人记不住。他们只能一个个去问,或者翻代码。备份漏了一个目录,往往要等到出事才知道。开源项目stdlayout:每个项目从第一天起,就有同一套目录和 .gitignorestdlayout是一个开源项目。就为了解决上述痛点。它其实就是一个Python文件。这个脚本干的就是这件事stdlayout 的Python 文件,叫init_project.py。你直接下载下来复制到项目根目录,运行:python3 init_project.py它做三件事。第一,建一套固定的目录,所有项目都一样。要提交的:deploy/(部署和健康检查脚本)、config-ops-template/(配置模板,只放占位值)、data-ops/(一个sources.yaml,写明数据在哪)、tests/、manual-tests/、third-party/、reference-data/。不提交的:config-ops/(真实配置和密钥)、data/、db/、upload/、logs/、tmp/、private-docs/。真实配置永远在一个被忽略的目录里,模板永远在一个不会被忽略的目录里,不用靠记性。做备份的人也只需要看data-ops/sources.yaml,就知道该备份什么。第二,补全 .gitignore,覆盖三十多种语言。Python、Node/TypeScript、Rust、Go、Java/Kotlin、C/C、Swift、C#/VB.NET/.NET、Visual Studio、Android、Flutter/Dart、CUDA、ActionScript、Julia、Ada、Fortran、Haskell、Lua、OCaml、Perl、Qt、R、Ruby、Delphi一共 32 个可选的语言段。你的项目只用其中两三种,就加--lang python go,不会塞进一堆用不上的规则。默认全部选上能让你放心在项目中使用不同的语言做开发。不该被git管理的各类生成物都不会被误提交到git上。脚本写的内容都包在一对BEGIN/END注释里。你自己写的规则在块外面,它不会碰;你已经有的规则,它不会重复加。package-lock.json、Cargo.lock、go.sum这类锁文件,它故意不忽略,因为你需要提交它们。第三,跑完之后自己检查。它会用git check-ignore实际问一遍 git:config-ops/到底有没有被忽略?deploy/会不会被误伤?被忽略的目录下有没有文件已经被跟踪了?任何一项不对,退出码是 1,放进 CI 就能拦住。它不会做的它不会覆盖你已有的文件,运行两遍,第二遍什么都不改。它也不会在不是 git 仓库顶层的目录里乱动手:你要是把脚本复制错了地方,它会告诉你,然后退出。想让它顺便git init,加--git-init。想反悔,--undo能撤销脚本生成的东西,但只撤销你没改过的;先加--dry-run看一眼。项目已经有自己的目录结构了,不想要我们的目录,只想要这份 .gitignore?用--gitignore-only,它只写那一块,别的什么都不建。完整的命令行参数推荐你直接复制到你的目录下不添加参数直接执行python3 init_project.py即可。如果你的需求比较复杂请参考下面完整的命令行参数。完整的--help下面是python3 init_project.py --help的完整输出(命令行输出只有英文),每一处后面附了中文对照翻译。$ ./init_project.py --help usage: init_project.py [-h] [--data [DIR ...]] [--lang [LANG ...]] [--docs {auto,yes,no}] [--name-prefix P] [--no-deploy] [--no-config] [--no-third-party] [--no-reference-data] [--no-manual-tests] [--no-tests] [--no-data-ops] [--gitignore-only] [--git-init] [--undo] [--dry-run] [--version] [path] stdlayout: complete a projects standard directories, .gitignore and structure docs. positional arguments: path project directory (default: the directory of this script, so copying it into the project root just works) options: -h, --help show this help message and exit --data [DIR ...] extra data directories (created and gitignored) --lang [LANG ...] only add ignores for these languages: python node typescript rust go java kotlin c cpp swift csharp vb fsharp dotnet visualstudio android flutter dart cuda actionscript julia ada fortran haskell lua ocaml perl qt r ruby delphi pascal (default: all) --docs {auto,yes,no} generate the structure docs (English Chinese). auto only when the project has no files yet --name-prefix P expected repo-name prefix; only warns on mismatch (e.g. 5) --no-deploy do not create deploy/ --no-config do not create config-ops-template/ --no-third-party do not create third-party/ --no-reference-data do not create reference-data/ --no-manual-tests do not create manual-tests/ --no-tests do not create tests/ --no-data-ops do not create>对照翻译用法:init_project.py [-h] [--data [DIR ...]] [--lang [LANG ...]] [--docs {auto,yes,no}] [--name-prefix P] [--no-deploy] [--no-config] [--no-third-party] [--no-reference-data] [--no-manual-tests] [--no-tests] [--no-data-ops] [--gitignore-only] [--git-init] [--undo] [--dry-run] [--version] [path]stdlayout:补全项目的标准目录、.gitignore 和结构说明文档。位置参数参数含义path项目目录(默认:本脚本所在的目录,所以把脚本复制到项目根目录就能直接用)选项选项含义-h, --help显示帮助信息并退出--data [DIR ...]额外的数据目录(会被创建,并加入 gitignore)--lang [LANG ...]只为这些语言添加忽略规则:python node typescript rust go java kotlin c cpp swift csharp vb fsharp dotnet visualstudio android flutter dart cuda actionscript julia ada fortran haskell lua ocaml perl qt r ruby delphi pascal(默认:全部)--docs {auto,yes,no}生成结构说明文档(英文 中文)。auto 仅当项目下还没有文件时才生成--name-prefix P期望的仓库名前缀;不匹配时只提示、不报错(例如 5)--no-deploy不创建deploy/--no-config不创建config-ops-template/--no-third-party不创建third-party/--no-reference-data不创建reference-data/--no-manual-tests不创建manual-tests/--no-tests不创建tests/--no-data-ops不创建data-ops/sources.yaml--gitignore-only只在.gitignore里创建 stdlayout 块(适合有自己目录结构的项目):不建目录,也不生成其他文件;如果该块已经存在,.gitignore保持不动--git-init如果目录还不是 git 仓库,先执行git init,再做其余的事--undo撤销本脚本生成的内容,但只撤销你没改过的(未修改的文件、空目录、.gitignore里的 stdlayout 块);可与--dry-run一起用来预览--dry-run显示会做什么,不改动任何东西--version显示程序版本号并退出stdlayout:补全项目的标准目录、.gitignore 和结构说明文档。只用标准库。可以放心重复运行:绝不覆盖文件,只追加缺少的.gitignore行。python3 init_project.py # 复制到项目根目录后运行 python3 init_project.py /path/to/project # 指定另一个目录 python3 init_project.py --data cache models # 额外的数据目录(创建并忽略) python3 init_project.py --lang python go # 限定语言的忽略规则(默认:全部) python3 init_project.py --gitignore-only # 只写 .gitignore 块;不建目录,不生成其他文件 python3 init_project.py --git-init # 还不是 git 仓库?先 git init,再做其余的事 python3 init_project.py --undo # 撤销它生成的内容,但只撤销你没改过的 python3 init_project.py --dry-run # 显示它会做什么,不改动任何东西 python3 init_project.py --version # 打印版本号没有--git-init时,不是 git 仓库的目录会原样保留、什么都不动(你可能把脚本复制错了地方)。它做什么、为什么这样做:https://github.com/performai-org/stdlayout/blob/main/docs/PROJECT_STRUCTURE.mdhttps://github.com/performai-org/stdlayout/blob/main/docs/PROJECT_STRUCTURE.zh-CN.md(中文)想看看源码和中英文文档都在这里,MIT 协议:https://github.com/performai-org/stdlayout
