DVC Local Command 用户手册（User Manual）

一、DVC目录层次结构命名规范

DVC 通过 4 层基础目录结构管理设计数据，每层命名需严格遵循规范以确保统一性。层级依次为：

Phase (阶段)
Block (模块)
Stage (步骤)
Version (版本)

1. Phase (阶段)

定义：划分项目生命周期，由项目经理 (Project Manager) 定义。 命名规则：格式为 P<数字>-<阶段描述>，如 P1-trial, P2-stable 等。说明：阶段名称需全局唯一，推荐使用标准阶段名称。

2. Block (模块)

定义：表示设计的功能模块，由设计经理 (Design Manager) 定义。 命名规则：一般为小写英文简写，如 top, cpu, ddr, sub1。说明：模块名称应与物理设计层级一致，避免使用特殊字符。

3. Stage (步骤)

定义：标识设计流程中的关键节点，如 RTL、DFT、APR 等。 命名规则：格式为 <三位数字>-<功能>，如：

000-DATA
200-LOGIC
300-DFT
400-APR
500-TIMING
600-POWER
700-TAPEOUT

4. Version (版本)

定义：表示 Stage 下的设计版本，由设计工程师命名。 命名规则：建议格式为 <日期>_<用途>，如：

20240615_init
20240701_final
20240628_fixmbist

示例结构：

P1-trial/
└── cpu/
    └── 000-DATA/
        └── 20240628_fixmbist/

一、概述

dvc local 命令用于支持工程师在本地工作区 /projects/<proj_code>/DVC/ 下进行设计数据的版本管理与暂存。本命令集主要服务于设计工程师在设计流程初期阶段的数据提交、备份、测试整合等非正式（pre-review）用途。当设计版本完成、通过 CID Review 后，将由 PM 使用 dvc 命令导入 DVC SVN 版本区。

1.1 公用数据目录与环境变量

公用 DVC 路径：/projects/<proj_code>/DVC/
设置环境变量：

  setenv DVC_LOCAL /projects/<proj_code>/DVC/

工程师操作所有 local create/put/delete 命令时，所指定的 <PHASE>/<BLOCK>/<STAGE>/<VERSION> 路径皆相对于 $DVC_LOCAL。

二、命令总览

命令	功能描述
dvc local create	创建 4 层版本目录结构
dvc local put	上传/链接文件/目录
dvc local delete	删除文件、目录、版本

三、命令详解与使用示例

3.1 dvc local create

【功能】

建立本地设计资料目录结构，共 4 层：<PHASE>/<BLOCK>/<STAGE>/<VERSION>。

【语法】

dvc local create <PHASE>/<BLOCK>/<STAGE>/<VERSION>

【示例】

dvc local create P1/cpu/000-DATA/20250618_init

【说明】

不可省略任一层级；
若上层目录不存在，将自动递归创建。

3.2 dvc local put

【功能】

上传文件至指定版本目录，可支持重命名、建立符号链接、嵌套目录上传等。

【语法】

dvc local put <VER_PATH> <src[:dest]> [--link]

【使用方式】

上传单个文件：dvc local put P1/cpu/000-DATA/20250618_init ./test1
上传并更名：dvc local put P1/cpu/000-DATA/20250618_init test1:new_test1
上传并建立链接：dvc local put P1/cpu/000-DATA/20250618_init test1:link_test1 –link
上传至子目录：dvc local put P1/cpu/000-DATA/20250618_init/subdir1 test1
上传整个目录：dvc local put P1/cpu/000-DATA/20250618_init dirx/

3.3 dvc local delete

【功能】

删除文件、目录、链接或整个版本/阶段/区块/阶段组。

【语法】

dvc local delete <PATH> [--force]

【类型与限制】

类型	是否需要 –force	说明
单一文件	否	若未使用 `--force`，将提示确认
子目录/链接	否	若未使用 `--force`，将提示确认
Version (整个版本目录)	无法跳过确认	一律要求交互式确认，即使使用 `--force` 也不例外
Stage	无法跳过确认	同上
Block	无法跳过确认	同上
Phase	无法跳过确认	同上

⚠️ --force 选项用于跳过删除确认流程，但下列类型的删除将始终要求用户明确确认，即使加上 --force 也无效：

Entire version folders (e.g., …/20250505_init)

Complete stages (e.g., …/000-DATA)

Blocks (e.g., …/test_design)

Phases (e.g., …/test_rel)

【示例】

删除文件：dvc local delete P1/cpu/000-DATA/20250618_init/test1 --force
删除整版本：dvc local delete P1/cpu/000-DATA/20250618_init

3.4 记录Log

使用”dvc local”command时, 会将其记录持续附加在log之内

${DVC_LOCAL}/dvc_local.log

其内容如下

<User_name>  <DATE_time>
Pwd: <current_folder_path>
Cmd: <user’s whole command in CLI>
Rlt:
  <command result messge> 
---------------------------------------------
<User_name>  <DATE_time>
Pwd: <current_folder_path>
Cmd: <user’s whole command in CLI>
Rlt:
  <command result messge>
---------------------------------------------
...

ps: include stdout and stderr messages

四、DVC Local 运作架构

使用者	场景	操作命令
工程师	本地编辑、整合、测试	`dvc local create/put/delete`
项目经理	提交正式版本进 SVN 仓库	`dvc folder checkout/checkin` 等

五、注意事项

版本目录结构必须为 4 层，否则命令执行将失败；
删除 Version/Stage/Block/Phase 时，务必检查影响范围；
本地路径为实际文件存储路径，与 SVN 独立。

六、常见问题（FAQ）

Q：上传时目标文件名重复会覆盖吗？
- A：会提示错误，需明确使用 new_name 或先删除旧文件。

七、附录

P1/
├── cpu/
│   └── 000-DATA/
│       └── 20250618_init/
│           ├── netlist.v
│           ├── constraint.sdc
│           └── README.txt