Repository: baidu/m-git Branch: master Commit: 582913c5566c Files: 109 Total size: 334.7 KB Directory structure: gitextract_p54qz427/ ├── .gitignore ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── Gemfile ├── LICENSE ├── README.md ├── Rakefile ├── docs/ │ ├── commands/ │ │ └── commands.md │ ├── config/ │ │ ├── config-env.md │ │ └── manifest.md │ ├── design/ │ │ ├── design.md │ │ ├── principle.md │ │ └── workspace.md │ ├── extension/ │ │ ├── cmd_ext.md │ │ ├── hooks.md │ │ ├── plugins.md │ │ └── submodule.md │ ├── faq/ │ │ └── faq.md │ ├── references.md │ └── use/ │ ├── common-commands.md │ └── how-to-start.md ├── lib/ │ ├── m-git/ │ │ ├── argv/ │ │ │ ├── opt.rb │ │ │ ├── opt_list.rb │ │ │ └── parser.rb │ │ ├── argv.rb │ │ ├── base_command.rb │ │ ├── command/ │ │ │ ├── add.rb │ │ │ ├── branch.rb │ │ │ ├── checkout.rb │ │ │ ├── clean.rb │ │ │ ├── commit.rb │ │ │ ├── config.rb │ │ │ ├── delete.rb │ │ │ ├── fetch.rb │ │ │ ├── forall.rb │ │ │ ├── info.rb │ │ │ ├── init.rb │ │ │ ├── log.rb │ │ │ ├── merge.rb │ │ │ ├── pull.rb │ │ │ ├── push.rb │ │ │ ├── rebase.rb │ │ │ ├── reset.rb │ │ │ ├── self.rb │ │ │ ├── stash.rb │ │ │ ├── status.rb │ │ │ ├── sync.rb │ │ │ └── tag.rb │ │ ├── command_manager.rb │ │ ├── error.rb │ │ ├── foundation/ │ │ │ ├── constants.rb │ │ │ ├── dir.rb │ │ │ ├── duration_recorder.rb │ │ │ ├── git_message_parser.rb │ │ │ ├── lock.rb │ │ │ ├── loger.rb │ │ │ ├── mgit_config.rb │ │ │ ├── operation_progress_manager.rb │ │ │ ├── timer.rb │ │ │ └── utils.rb │ │ ├── foundation.rb │ │ ├── hooks_manager.rb │ │ ├── manifest/ │ │ │ ├── cache_manager.rb │ │ │ ├── internal.rb │ │ │ ├── light_repo.rb │ │ │ ├── light_repo_generator.rb │ │ │ ├── linter.rb │ │ │ └── manifest.sample │ │ ├── manifest.rb │ │ ├── open_api/ │ │ │ └── script_download_info.rb │ │ ├── open_api.rb │ │ ├── output/ │ │ │ └── output.rb │ │ ├── plugin/ │ │ │ ├── completion.bash │ │ │ ├── completion.zsh │ │ │ └── init.sh │ │ ├── plugin_manager.rb │ │ ├── repo/ │ │ │ ├── status.rb │ │ │ └── sync_helper.rb │ │ ├── repo.rb │ │ ├── template/ │ │ │ ├── local_manifest.rb │ │ │ ├── manifest_hook.rb │ │ │ ├── post_download_hook.rb │ │ │ ├── post_hook.rb │ │ │ ├── pre_exec_hook.rb │ │ │ ├── pre_hook.rb │ │ │ └── pre_push_hook.rb │ │ ├── template.rb │ │ ├── version.rb │ │ ├── workspace/ │ │ │ ├── path_helper.rb │ │ │ └── workspace_helper.rb │ │ └── workspace.rb │ └── m-git.rb ├── m-git.gemspec ├── manifest.json ├── mgit └── test/ ├── argv/ │ ├── test_opt.rb │ ├── test_opt_list.rb │ └── test_parser.rb ├── foundation/ │ ├── test_dir.rb │ ├── test_mgit_config.rb │ └── test_utils.rb ├── manifest/ │ └── test_light_repo.rb ├── test_argv.rb ├── test_foundation.rb ├── test_helper.rb ├── test_manifest.rb ├── test_open_api.rb ├── test_plugin_manager.rb └── test_workspace.rb ================================================ FILE CONTENTS ================================================ ================================================ FILE: .gitignore ================================================ /.bundle/ /.yardoc /_yardoc/ /coverage/ /doc/ /pkg/ /spec/reports/ /tmp/ .bundle vendor/ *.gem ## IDE *.xccheckout .idea ## File *.svn/ *.DS_Store .DS_Store? ## other *.pyc # log指令缓存 log_cache.json ================================================ FILE: CHANGELOG.md ================================================ ## Release Note: ### 2.5.5 -【bug修复】修复 box config -m 命令 不可用问题，修改参数类型为String ### 2.5.4 - mgit增加inject注入文件功能 - 增加manifest.json文件，当前仓库可用于mgit-demo ================================================ FILE: CODE_OF_CONDUCT.md ================================================ # Contributor Covenant Code of Conduct ## Our Pledge In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. ## Our Standards Examples of behavior that contributes to creating a positive environment include: * Using welcoming and inclusive language * Being respectful of differing viewpoints and experiences * Gracefully accepting constructive criticism * Focusing on what is best for the community * Showing empathy towards other community members Examples of unacceptable behavior by participants include: * The use of sexualized language or imagery and unwelcome sexual attention or advances * Trolling, insulting/derogatory comments, and personal or political attacks * Public or private harassment * Publishing others' private information, such as a physical or electronic address, without explicit permission * Other conduct which could reasonably be considered inappropriate in a professional setting ## Our Responsibilities Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. ## Scope This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at baidu. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. ## Attribution This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version] [homepage]: http://contributor-covenant.org [version]: http://contributor-covenant.org/version/1/4/ ================================================ FILE: Gemfile ================================================ source "https://gems.ruby-china.com" # git_source(:github) {|repo_name| "https://github.com/#{repo_name}" } # Specify your gem's dependencies in mgit.gemspec gemspec ================================================ FILE: LICENSE ================================================ The MIT License (MIT) Copyright (c) 2020 Baidu, Inc. All Rights Reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: README.md ================================================ # MGit MGit 是一款 Ruby 封装的基于 Git 的多仓库管理工具，可以高效的、同时的对多个 Git 仓库执行 Git 命令。 适合于在多个仓库中进行关联开发的项目，提高 Git 操作的效率，避免逐个执行 Git 命令带来的误操作风险。 - **易用的命令** 封装 Git 命令，命令和参数均由 Git 衍生而来，会使用 Git 就可以成本低上手 MGit。 - **直观高效的执行命令** 提供图表化的结果展示，开发者可以快速查看命令在多个仓库的执行结果； 多线程并发执行多仓库命令，通过仓库缓存机制提高仓库的拉取效率； - **安全的执行命令** 在执行命令前对多仓库状态进行安全检查：分支是否异常，工作区是否未提交代码等； 对 .git 进行托管与 Git 工作区分类，避免误删丢失改动或提交； 执行存在风险的操作时，会给与风险操作提示，避免误操作； - **方便扩展** 支持加载 ruby-gem 包作为插件，gem 包名格式 `m-git-${suffix}`和`mgit-${suffix}` 快速的扩展 MGit 的命令，增加自定义命令，扩展已有命令的功能； 提供类似`git hook`的 hook 点，方便开发者实现自定义逻辑； ## 快速开始 #### 1、安装 MGit 工具 环境要求： - 系统：支持 macOS、Ubuntu，暂时不支持 Windows - Ruby版本: >= 2.3.7 ```ruby $ gem install m-git ``` #### 2、初始化多仓库 初始化多仓库使用 `mgit init` 命令; 类似于 Git 从远程 clone 新仓库, 会将多个仓库 clone 到本地; 下面通过一个 demo 体验一下 MGit 命令： ```ruby # 2.1 建议在一个新文件夹中拉取demo $ mgit init -g https://github.com/baidu/m-git.git # 2.2 体验一下mgit命令 $ mgit -l 显示所有mgit管理的仓库 $ mgit branch --compact 查看多仓库的分支 $ mgit status 产看仓库分支超前/落后情况 ``` #### 3、已有多仓库如何迁移到 MGit 管理 - 根据文档[配置 manifest.json](docs/config/manifest.md) 将要管理的仓库都配置到 manifest.json 中 - 将 manifest.json 放到一个仓库中管理 这个仓库同样会在 manifest.json 中描述，并且需要配置 "config-repo": true 这个仓库称为配置仓库，也叫做**主仓库**，其他仓库叫做**子仓库** - 使用 `mgit init -f manifest文件路径` 初始化多仓库，命令测试 manifest.json 配置是否正常 注意这个命令不会重复拉取主仓库，只会拉取所有的子仓库到当前目录，并在当前目录创建一个.mgit 你可以在当前目录中看到每个仓库的源码，他们的路径可以通过 manifest.json 的 dest字段配置 你也可以在 .mgit/source-git/ 下看到所有仓库的.git, 这是 MGit 对所有仓库的托管 - 本地测试成功后，你可以提交主仓库中的 manifest.json，推送主仓库的变更到远端 - 通过 `mgit init -g 主仓库地址` 命令初始化多仓库 #### 4、进一步了解 MGit [常用命令](docs/use/common-commands.md) [manifest文件介绍](docs/config/manifest.md) [配置多仓库](docs/config/config-env.md) [使用 MGit 管理多仓库的案例](docs/use/how-to-start.md#4-mgit-) [了解更多](docs/references.md) ## 测试 单测在MGit仓库内的test文件夹下 新建单测文件，必须以‘test_’开头 执行单测：rake （如果报错尝试执行 bundle install） ## 如何贡献 欢迎开发者向 MGit 贡献代码。如果您开发了新功能或发现了 bug，欢迎给我们提交PR。 代码贡献要求： 1. 功能和实现应该具有通用性, 不是为了解决某个具体业务而定制的代码逻辑 2. 代码质量高，符合 Ruby 编码规范 3. 需要补充对应的单测 case issues贡献： 如在使用中遇到问题，请在 https://github.com/baidu/m-git/issues 新建 issues 反馈问题。 ================================================ FILE: Rakefile ================================================ require "bundler/gem_tasks" task :default => :test require 'rake/testtask' Rake::TestTask.new(:test) do |t| t.libs << "test" t.pattern = 'test/**/test_*.rb' t.verbose = true end ================================================ FILE: docs/commands/commands.md ================================================ ## Command-line Reference 参考：https://guides.cocoapods.org/terminal/commands.html#pod_spec_lint # Brief Description Of Commands ## Initalizing + mgit + config 用于更新多仓库配置信息。 ## Creating && Workspace + init 初始化多仓库目录。 + sync 根据配置表(从远端或本地)同步仓库到工作区，包括被锁定仓库，已经在工作的不作处理（默认不执行pull）。 + info 输出指定仓库的信息。 + clean 对指定或所有仓库执行"git add . && git reset --hard"操作，强制清空暂存区和工作区。 + delete 删除指定单个或多个仓库（包含被管理的.git文件和工程文件以及跟该.git关联的所有缓存）。 ## Snapshotting + add 将文件改动加入暂存区。 + status 输出所有仓库的状态。包括："分支"，"暂存区"，"工作区"，"特殊（未跟踪和被忽略）"，"冲突"。 + commit 将修改记录到版本库。 + reset 将当前HEAD指针还原到指定状态。 ## Branching + branch 列出，创建和删除分支。 + checkout 切换分支或恢复工作区改动。 + merge 合并两个或多个开发历史。 + stash 使用git stash将当前工作区改动暂时存放起来。 + tag 增删查或验证标签。增加标签示例：mgit tag -a 'v0.0.1' -m 'Tag description message' + log 输出指定仓库的提交历史。 ## Trunk + fetch 从远程仓库下载数据对象和引用。 + pull 从仓库或本地分支获取数据并合并。 + rebase 重新将提交应用到其他基点，该命令不执行lock的仓库。 + push 更新远程分支和对应的数据对象。 ## Addition + forall 对多仓库批量执行指令。 ================================================ FILE: docs/config/config-env.md ================================================ ### config.yml 介绍 config.yml 是 MGit 的配置文件； MGit的配置内容保存在多仓库目录下的`.mgit/config.yml`文件中，配置仅针对当前的多仓库生效； - 通过 `$ mgit config --list` 可以查看当前config.yml中的配置 ```ruby [是否将.git实体托管给MGit，托管后仓库内的.git目录是软链 (true/false)] managegit: true [MGit操作的最大并发数? (Integer)] maxconcurrentcount: (默认当前机器的逻辑 CPU 数) [是否按照配置表同步工作区? (true/false)] syncworkspace: true [同步工作区时回收的仓库是否保留到缓存中? (true/false)] savecache: false [是否开启日志打印，操作日志会收集到.mgit/log目录下? (true/false)] logenable: true [日志的打印级别, DEBUG = 0, INFO = 1, WARN = 2, ERROR = 3, FATAL = 4] loglevel: 0 ``` - 通过 `$ mgit config --set` 可以对config.yml进行配置，如："mgit config -s maxconcurrentcount 20" - 当前支持的几个配置项： | key | 类型 | 描述 | 默认值 | | ------------------ | :------ | ------------------------------------------------------------ | ------ | | managegit | Boolean | 如果该配置为`true`, 那么在通过MGit下载新仓库时（`mgit sync -n`)，会将工作区仓库内的`.git`托管给MGit（将`.git`移动到`.mgit/source-git/`下）。若配置为`false`，则任何情况下都不操作`.git`, 如有`.git`已经被托管，则弹出到工作区。 | true | | maxconcurrentcount | Integer | MGit操作的最大并发数. | 当前机器的逻辑 CPU 数 | | syncworkspace | Boolean | 当配置表发生改变的时候，工作区内的仓库可能和配置表不匹配，若配置为`true`，会将上次操作和本地操作依据的配置表做对比，将多余的仓库（如有的话）缓存到`/.mgit/source-git/.../cache`目录下。若配置为`false`，则不操作。 | true | | savecache | Boolean | 同步工作区时回收的仓库被放到缓存中后，若配置为`true`，则一直保留该工作区目录，若配置为`false`，则直接删除(`.git`被托管的仓库可以删除工作区，需要时导出即可)。该配置在`syncworkspace`为`false`时不生效。 | false | | logenable | Boolean | 是否开启日志打印，操作日志会收集到.mgit/log目录下 | true | | loglevel | Integer | 日志的打印级别, DEBUG = 0, INFO = 1, WARN = 2, ERROR = 3, FATAL = 4 | 1 | - 关于 managegit 与 syncworkspace 配置的详细说明 建议配置： - managegit ：true - syncworkspace ： true 在使用MGit管理多仓库时，当前分支dev-1分支 有 a、b、c 三个仓库； 1、现在需要checkout到一个旧分支feature-1，feature-1只配置了 a、b仓库，此时c仓库会被MGit回收，不会展示在当前工作区（syncworkspace ： true 按照配置表同步工作区） 2、但c仓库还有未推到远端的开发分支和stash的代码，MGit会托管暂时不用的c仓库，保证本地c仓库中的的代码不会丢失（ managegit: true 托管工作区） 3、当再checkout到dev-1分支时，会将被托管的c仓库同步回工作区（syncworkspace ： true 按照配置表同步工作区） ================================================ FILE: docs/config/manifest.md ================================================ ### 1. manifest 配置介绍 manifest.json 配置表定义了多仓库管理所需的仓库信息，采用json格式，示例如下： ```ruby { "remote": "https://github.com/baidu",//远程仓库地址 "version":1, //配置文件版本 "mgit-excluded": false, "dest": "Sources", //本地仓库相对mgit根目录存放路径 "repositories": { //源码列表，包含git仓库和非git仓库 "MainApp": { "remote-path": "mainapp" //远程仓库名，对于需要mgit管理的仓库是必需字段。此时git地址为：https://github.com/baidu/mainapp "config-repo": true //指定该仓库为配置仓库，即包含本配置表的仓库，仅允许指定一个仓库 }, "Watch": { "remote-path": "watch" "dest":"temp/test" //可选，覆盖最外层定义，在mgit根目录下仓库的父目录。该仓库本地路径为"/temp/test/Watch" }, "BBAAccount": { "remote-path": "bbaaccount", "abs-dest":"/Users/someone/baidu/temp/my_account" //仓库本地完整路径（指定后dest无效） }, "Script": { "remote-path": "script", "remote": "https://github.com/some_script",//可选，覆盖最外层定义 "lock": { "branch":"my_branch"//当前分支 或"tag":"tag1"//tag 或"commit_id":"123456"//HEAD指向的commit id }//锁定某仓库状态，每次执行指令时会保持该仓库为指定的状态 }, "Some_Repo": { "remote-path": "some_repo", "mgit-excluded": true//指定不进行多仓库管理，可选 }, //本地git仓库或非git仓库（mgit不操作） "New_Repo": { "dest": "Some/Dir", "mgit-excluded": true }， "Test_Repo": { "dest": "Some/Dir2", "dummy": true //（2.3.0已废弃）指定该仓库为占位仓库（mgit不操作，EasyBox组装器也不使用） } } } ``` ### 2. manifest 配置中的具体字段介绍 #### 2.1 一级字段 | 字段名 | 说明 | 必要性 | 值类型 | | :-------------- | :----------------------------------------------------------- | :----- | :------------------- | | `remote` | 远程仓库git地址的根目录。注意，完整地址为`/`。 | 必需 | `String` | | `version` | 配置文件版本。 | 必需 | `Number` | | `dest` | 在mgit根目录下仓库的父目录，此时完整本地目录为：`//`。 | 必需 | `String` | | `mgit-excluded` | 指定为`true`则不被mgit纳入多仓库管理，即mgit不会操作该仓库。 | 可选 | `Bool` | | `repositories` | 源码列表。 | 必需 | `JSON` | #### 2.2 `repositories`内的Json数据 | 字段名 | 说明 | 值类型 | | :------------ | :----------------------------------------------------------- | :----- | | `` | 仓库唯一标识，值为该仓库的配置。在`dest`生效时，为本地仓库目录名，此时完整本地目录为：`//`。 | `JSON` | #### 2.3. 仓库配置字段 | 字段名 | 说明 | 必要性 | 值类型 | | :-------------------- | :----------------------------------------------------------- | :----------------------------------------------------------- | :------- | | `remote-path` | 远程仓库git地址相对路径。注意，完整的远程地址为`/`。 | 有条件可选：在不显式指定`mgit-excluded`为`true`的情况下（即希望该仓库纳入mgit管理的话），是必须字段，否则可选。 | `String` | | `remote` | 远程仓库地址根目录，如果指定则覆盖一级字段的`remote`。注意，完整的远程地址为`/`。 | 可选 | `String` | | `lock` | 指定后会锁定仓库状态，每次执行指令时会保持该仓库为锁定状态。状态可以指定`branch`, `tag`, `commit_id`中的一个，如`lock: { "branch": "master" }`。 | 可选 | `Json` | | `dest` | 本地仓库相对mgit根目录存放的父目录，如果指定则覆盖一级字段的`dest`。此时完整本地目录为：`//`。 | 可选 | `String` | | `abs-dest` | 本地仓库的完整存放路径，如果指定则`dest`失效，此时仓库完整的本地路径为``。 | 可选 | `String` | | `config-repo` | 如果指定为`true`则表明该仓库为包含该配置文件的配置仓库，最多只能指定一个。注意，指定了该仓库后，某些mgit操作会优先处理该仓库，如`checkout`,`merge`，`pull`。 | 可选 | `Bool` | | `mgit-excluded` | 指定为`true`则mgit不操作，此处指定会覆盖一级字段的`mgit-excluded`。 | 可选 | `Bool` | | `[2.3.0已废弃] dummy` | 指定为`true`则表明该仓库是占位仓库，不受mgit操作，同时EasyBox组装器也不使用它的**源码**，单纯用于记录仓库信息，如一些完全二进制的三方库。

**提示**：指定`dummy:true`后，则默认指定`mgit-excluded:true`（如果显示指定了`mgit-excluded:false`，依然将其置为`true`）。该字段用于配合EasyBox进行工程组装，日常使用无需添加。 | 可选 | `Bool` | - **mgit根目录**是指mgit初始化的目录，在该目录下存在`.mgit`隐藏文件。 - 配置表文件名必须是`manifest.json` - 配置表中同名字段覆盖优先级：仓库配置 > 全局配置。 - 对于值为`Bool`类型的字段，缺省意味着该字段值为`false`。 - 采用包含配置表的中央仓库的方式管理多仓库时，需要将配置仓库的配置也描述在配置表中。 ### 3. 本地配置表 local_manifest 当你想在本地调试时，可以通过创建`local_manifest.json`临时修改多仓库配置；可以在不修改`manifest.json`的情况下对配置进行调整； 可以选择以下方式创建 local_manifest.json： - 通过 `migt init` 命令自动创建 - 执行命令时不带参数`-l`参数 将自动在配置仓库创建不生效的`local_manifest.json`，内容为： ```ruby { "repositories": { // 可自行根据需要添加/修改仓库配置 } } ``` - 执行命令时添加参数`-l` 则在配置仓库创建`local_manifest.json`，此时该文件只包含配置仓库信息： ```ruby // 此配置的含义：让mgit只管理配置仓库，其余仓库均不管理，主要用于简化壳工程初始化。 { "mgit-excluded": true, "repositories": { "config_repo_name": { "mgit-excluded": false } } } ``` - 通过 `mgit config` 命令创建 指定一个目录，在该目录下创建`local_manifest.json`，若目录不存在则自动创建。如： ```ruby $ mgit config -c /a/b/c ``` **注意**： * `/a/b/c`为包含配置文件的文件夹目录，此时生成配置文件`/a/b/c/local_manifest.json` * 如果未传入值，如：`mgit config -c`，那么若配置仓库存在的话，会在配置仓库中创建空的本地配置文件。 - 手动创建 local_manifest.json * 手动新建配置文件`local_manifest.json`，放到任意位置，执行以下指令将其托管给mgit： ``` //注意，此后如果local_manifest.json位置发生了移动，需要重新执行该指令使其生效。 $ mgit config -u /local_manifest.json ``` * 在不执行指令的情况下，可手动创建`local_manifest.json`并将其放置于下列目录即可自动生效: 将创建的local_manifest.json 放到`manifest.json`所在目录 或 `.mgit/source-config`文件夹内 即可生效 ### 4、 对local_manifest.json 校验与合并 - `local_manifest.json`文件的字段与`manifest.json`完全一致，唯一区别是不会对它做字段合法性校验，对于不需要覆盖的字段可以缺省。 - 执行mgit指令时，会将`manifest.json`和`local_manifest.json`合并，配置文件中的字段会被本地配置文件中定义的对应字段覆盖（`repositories`字段除外，而是仓库配置内的对应字段被覆盖），如： ```ruby // manifest.json: { "remote":"https://github.com/baidu", "version":1, "dest":"Sources", "repositories": { "TestRepo1": { "remote-path":"test1.git", "mgit-excluded": false } } } // local_manifest.json: { "remote":"https://github.com/baidu", //覆盖原定义 "repositories": { //将manifest.json内定义的TestRepo1排除管理 "TestRepo1": { "mgit-excluded": true }， //添加一个新仓库，配置完成后执行mgit sync -n可下载该仓库 "TestRepo2": { "remote-path":"test.git" } } } // 将合并为： { "remote":"https://github.com/baidu", //被覆盖 "version":1, "dest":"Sources", "repositories": { "TestRepo1": { "remote-path":"test1.git", "mgit-excluded": true //被覆盖 }, //被添加 "TestRepo2": { "remote-path":"test.git" } } } ``` ================================================ FILE: docs/design/design.md ================================================ ## 设计篇(略) ### 基本架构 ================================================ FILE: docs/design/principle.md ================================================ ## 基本原则 ================================================ FILE: docs/design/workspace.md ================================================ ### 工作区 ================================================ FILE: docs/extension/cmd_ext.md ================================================ ### 一、扩展指令 MGit 加载插件有**2种方式**： - **ruby gem 包加载** 当运行 MGit 命令时，从所有的`ruby-gems`包中查找并加载 MGit 的插件，查找判定条件 gem 包中存在如下文件： ``` - m-git_plugin.rb - mgit_plugin.rb ``` > Tips：插件功能开发完成后，打包为 gem 包后发布到 gem 源，MGit 执行命令时将自动被加载 - **inject 参数加载** ``` # 执行命令时加载插件 # path_to_plugin：可以是待加载的插件文件或文件夹， # 如果是文件夹，则从中查找插件文件(m-git_plugin.rb、mgit_plugin.rb)并加载 $ mgit add --inject=${path_to_plugin} ``` ### 1分钟极简扩展（以Demo多仓库示例，待修改demo url） **需求：**假设我们要提供一个命令用于查看 MGit 管理的所有 Git 仓库，创建一个新的指令：hi ``` $ mgit hi //输出当前mgit管理的仓库列表 ``` **Step0：**建议在一个新文件夹中拉取demo ``` mgit init -g https://github.com/baidu/m-git.git ``` **Step1：**新建一个文件：hi.rb （无所谓名称） **Step2：**增加一个继承自 BaseCommand 类的子类`Hi`，指令默认使用子类的名称，可使用`self.cmd`方法重写 ``` module MGit class Hi < BaseCommand def execute(argv) # Do something for each repo. puts all_repos.map(&:name).join(',') end end end ``` **测试：** ``` # inject 指向扩展命令的文件路径(或全路径) mgit hi --inject=hi.rb > m-git,DDParser ``` ================================================ FILE: docs/extension/hooks.md ================================================ ### hook #### 一、什么是hook hook是在MGit 仓库中特定事件触发后被调用的脚本。hook最常见的使用场景包括根据仓库状态改变项目环境、接入持续集成工作流等。 由于脚本是可以完全定制，所以你可以用hook来自动化或者优化你开发工作流中任意部分。 #### 二、MGit的hook hook脚本位于多仓库目录下的`/.mgit/hooks`内，下表列出个各hook的作用 | hook脚本 | 作用 | | --------------------- | ------------------------------------------------------------ | | pre_hook.rb | 指令执行前hook(执行时机较早，内部只能获取当前指令和多仓库根目录) | | post_hook.rb | 指令执行后hook | | pre_exec_hook.rb | 指令执行前hook(内部除当前指令和多仓库根目录外，还可获取执行仓库的 | | manifest_hook.rb | mgit读取配置文件前执行的hook | | post_download_hook.rb | mgit sync下载新仓库后执行的hook | | pre_push_hook.rb | mgit push前执行的hook(类似pre_exec_hook) | 【注意】执行顺序： 1. mgit指令pre_hook 2. mgit多仓库pre_hook 3. manifest_hook 4. pre_exec_hook/pre_push_hook/post_download_hook 5. git前置hook 6. git后置hook 7. mgit多仓库post_hook 8. mgit指令post_hook 如下代码是 pre_hook.rb 的模板: ``` #coding=utf-8 module MGitTemplate class PreHook # hook接口，用于接受本次指令执行前的数据 # # @param cmd [String] 本次执行指令 # # @param opts [String] 本次执行指令参数 # # @param mgit_root [String] mgit根目录 # def self.run(cmd, opts, mgit_root) end end end ``` ================================================ FILE: docs/extension/plugins.md ================================================ ### 插件 - 插件介绍，可以做什么 - 如何扩展插件 - 如何引用其他插件 ================================================ FILE: docs/extension/submodule.md ================================================ ### 用做子工具 - 介绍其他工具如何调用mgit作为模块 ================================================ FILE: docs/faq/faq.md ================================================ ## F.A.Q ================================================ FILE: docs/references.md ================================================
MGit相关文档
* [介绍](../README.md) * 使用篇 * [快速开始](use/how-to-start.md) * [常用命令](use/common-commands.md) * 配置篇 * [Manifest](config/manifest.md) * [config.yml](config/config-env.md) * 扩展篇 * [扩展指令](extension/cmd_ext.md) * [MGit Hooks](extension/hooks.md) * [F.A.Q](faq/faq.md) * [Command-line Reference](commands/commands.md) ================================================ FILE: docs/use/common-commands.md ================================================ ## 常用命令 > 指令描述符说明： > > < > : 占位参数 > > [ ] : 可选组合 > > ( ) ：必选组合 > > | : 互斥参数 > > ··· ：可重复指定前一个参数 ### mgit ` mgit [-l [-a]|-s] [-v] [-h]` | 特有参数 | 说明 | | ----------------- | ------------------------------------------------------------ | | `-a, --all` | 指定操作所有(包含不被mgit管理)的仓库，可配合`-l`合并使用: `mgit -al` | | `-h, --help` | 显示帮助。 | | `-l, --list` | 显示所有migt管理的仓库。 | | `-s, --size` | 显示所有仓库的磁盘占用量。 | | `-v, --version` | 显示mgit版本。 | | `-w, --workspace` | 显示当前mgit工程管理根目录(`.mgit`所在目录)。 | 【注意】使用`-l, --list`参数列出所有被mgit管理的仓库，以表格的形式输出，其中表格头部为包含该仓库的目录（相对mgit根目录），同时标明本地缺失仓库。 ### add ` mgit add [] [(--mrepo|--el-mrepo) ...] [--help]` 添加文件到暂存区 | 特有参数 | 说明 | | ------------ | ------------------------------------------------------------ | | `--mrepo` | 指定需要执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。 | | `--el-mrepo` | 指定需要排除执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--el-mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。与`--mrepo`同时指定时无效。 | | `--help` | 显示帮助。 | 【注意】执行前会校验各个仓库所在分支是否一致，否则会提示是否继续： ### branch `mgit branch [|--compact] [(--mrepo|--el-mrepo) ...] [--help]` 对多仓库进行分支操作 | 特有参数 | 说明 | | ------------ | ------------------------------------------------------------ | | `--mrepo` | 指定需要执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。 | | `--compact` | 以紧凑的方式显示所有仓库的当前分支。 | | `--el-mrepo` | 指定需要排除执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--el-mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。与`--mrepo`同时指定时无效。 | | `--help` | 显示帮助。 | 【注意】在指定`--compact`的情况下，其余传入的原生`git-branch-option`指令将不生效。指定`--compact`时，会将所有仓库的当前分支做一个归类，便于检查哪些仓库当前处于不同分支，对于特殊状态（HEAD游离和被锁定的仓库）也会显示出来。 ![图片](branch_command_01.png) ### checkout `mgit checkout [] [(--mrepo|--el-mrepo) ...] [--help]` 克隆远程仓库 | 特有参数 | 说明 | | ------------ | ------------------------------------------------------------ | | `--mrepo` | 指定需要执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。 | | `--el-mrepo` | 指定需要排除执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--el-mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。与`--mrepo`同时指定时无效。 | | `--help` | 显示帮助。 | 【注意】 1. 若指定了配置仓库，执行该指令时会先checkout配置仓库仓库，如果它本地有修改，则切换失败，需要自行将配置仓库处理干净后重试，也可以选择跳过继续。如果使用checkout切分支， 此处建议先**取消操作并清理配置仓库**的改动再重试，因为切换的目标分支上配置仓库中的配置文件可能与当前不同，不先完成它的切换，后续操作的仓库可能产生遗漏。 ![图片](checkout_command_01.png) 2. 在配置仓库切换成功后，会根据配置仓库内的配置表来`checkout`其余仓库，此时如果有异常状态仓库，会给出提示： ![图片](checkout_command_02.png) 3. 在配置仓库切换成功后，配置表可能发生改变，此时可能会遇到仓库缺失问题，如：A分支10个仓库，B分支11个仓库，当前从A分支切换到B分支，B分支多的1个仓库本地没有，此时会自动下载缺失仓库，并根据当前多数仓库所处分支进行推荐切换。 ![图片](checkout_command_03.png) ### clean `mgit clean [(-m|-e) ...] [-h]` 用于清空所有工作区和暂存区，即对所有仓库或指定仓库执行`git add . && git reset --hard` | 特有参数 | 说明 | | ---------------- | ------------------------------------------------------------ | | `-m, --mrepo` | 指定需要执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。 | | `-e, --el-mrepo` | 指定需要排除执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--el-mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。与`--mrepo`同时指定时无效。 | | `-h, --help` | 显示帮助。 | ### commit `mgit commit [] [(--mrepo|--el-mrepo) ...] [--help]` | 特有参数 | 说明 | | ------------ | ------------------------------------------------------------ | | `--mrepo` | 指定需要执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。 | | `--el-mrepo` | 指定需要排除执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--el-mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。与`--mrepo`同时指定时无效。 | | `--help` | 显示帮助。 | 【注意】 - 如果当前仓库的暂存区没有待提交内容的话，则不会执行`commit`操作。 - 执行前会校验各仓库分支是否统一。 - 本指令不支持交互式操作，因此不支持`--ammend`。 ### config ``` mgit config (-m|-u) mgit config -c mgit config (-l | -s ) mgit config -h ``` | 特有参数 | 说明 | | ----------------------- | ------------------------------------------------------------ | | `-c, --create-local` | 在指定目录下创建本地配置文件，若目录不存在则自动创建。如执行：`mgit config -c /a/b/c`，则生成本地配置文件：`/a/b/c/local_manifest.json`。如果未传入值，如：`mgit config -c`，那么会在配置仓库中创建本地配置文件(若配置仓库存在的话)。 | | `-m, --update-manifest` | 该指令用于更新mgit所使用的配置文件，如：`mgit config -m manifest.json`。 | | `-u, --update-local` | 该指令用于更新mgit所使用的本地配置文件，如：`mgit config -u /local_manifest.json`。 | | `-l, --list` | 列出当前MGit所有配置，无参数，如：`mgit config -l`。 | | `-s, --set` | 对MGit进行配置，遵守格式：`mgit config -s `，如：`mgit config -s maxconcurrentcount 5`。 | | `-h, --help` | 显示帮助。 | 命令使用细节请查看[config配置文档](../config/config-env.md) ### delete `mgit delete ... [-h]` 该指令用于删除单一仓库的，包括被mgit管理存在于.mgit文件夹中的git实体和存在.mgit外部的工程文件。 | 特有参数 | 说明 | | ------------ | ---------- | | `-h, --help` | 显示帮助。 | 【注意】如果需要删除某个仓库，仅仅手动删除.mgit外部的工程文件并不完整，还需要删除.mgit/source-git内的git实体，因此如果需要删除一个仓库的话，最好使用该指令来完整删除。 ### fetch `mgit fetch [] [(--mrepo|--el-mrepo) ...] [--help]` 从远程仓库获取代码 | 特有参数 | 说明 | | ------------ | ------------------------------------------------------------ | | `--mrepo` | 指定需要执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。 | | `--el-mrepo` | 指定需要排除执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--el-mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。与`--mrepo`同时指定时无效。 | | `--help` | 显示帮助。 | ### forall `mgit forall -c '' [(-m|-e) ...] [-n] [-h]` 该指令用于在指定（或所有）仓库上执行自定义指令 | 特有参数 | 说明 | | ------------------ | ------------------------------------------------------------ | | `-c, --command` | 指定需要执行的shell命令，如：`mgit -c "git status -s"`（注意要带引号）。 | | `-n, --concurrent` | 可选参数，若指定，则shell命令以多线程方式执行（若缺省则以单线程串行方式执行）。 | | `-m, --mrepo` | 指定需要执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。 | | `-e, --el-mrepo` | 指定需要排除执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--el-mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。与`--mrepo`同时指定时无效。 | | `-h, --help` | 显示帮助。 | ### info `mgit info ... [-h]` 产看一个仓库的信息 | 特有参数 | 说明 | | ------------ | ---------- | | `-h, --help` | 显示帮助。 | ### log `mgit log [-n] [-h]` 输出单一仓库的log | 特有参数 | 说明 | | -------------- | -------------------------------------------- | | `-h, --help` | 显示帮助。 | | `-n, --number` | 指定需要显示的提交log个数，不指定则默认500。 | ### merge ``` mgit merge [] [--pull] [(--mrepo|--el-mrepo) ...] [--help] mgit merge --continue mgit merge --abort ``` | 特有参数 | 说明 | | ------------ | ------------------------------------------------------------ | | `--mrepo` | 指定需要执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。 | | `--el-mrepo` | 指定需要排除执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--el-mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。与`--mrepo`同时指定时无效。 | | `--pull` | 可选参数，指定后在合并仓库前会自动拉取远程分支更新代码，否则会有交互式询问。如：`mgit merge --pull` | | `--continue` | MGit自定义参数，仅在操作多仓库过程中出现问题停止，执行状态进入中间态后可用。该参数只能单独使用，解决问题后可执行`mgit merge --continue`继续操作其余仓库。 | | `--abort` | Git原生参数，用于取消`git merge`中间态，但MGit做了增强，该参数可同时消除`mgit merge`中间态，且只能单独使用：`mgit merge --abort` | | `--help` | 显示帮助。 | 【注意】 1. 若指定了配置仓库，执行该指令时会先merge配置仓库，然后根据它内部的配置表merge其余仓库。配置仓库merge完成后，配置表可能发生改变，此时可能会检测到部分仓库本地缺失，此时会自动下载并引导分支切换（提示如checkout指令所述）。 2. 执行前会校验各仓库分支是否统一。 3. 中间态：由于该操作分为两段式，第一阶段操作配置仓库，第二阶段操作子仓库，且在操作前均可能拉取最新代码，如果操作失败会进入`中间态`。根据提示解决问题后执行`mgit merge --continue`即可继续执行，也可执行`mgit merge --abort`放弃操作。 4. 该指令默认添加`--no-ff`参数，如果需要fast-forwarding，请手动添加`--ff`。 ### pull ``` mgit pull [ [(--mrepo|--el-mrepo) ...] [--auto-exec] [--no-check] [--include-lock] [--help] mgit pull --continue` mgit pull --abort ``` | 特有参数 | 说明 | | ---------------- | ------------------------------------------------------------ | | `--auto-exec` | 指定该参数会跳过所有交互场景，并自动选择需要的操作执行。该参数主要用于脚本调用mgit进行自动化操作，日常RD开发不应当使用。 | | `--mrepo` | 指定需要执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。 | | `--el-mrepo` | 指定需要排除执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--el-mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。与`--mrepo`同时指定时无效。 | | `--no-check` | 指定该参数意味着执行前跳过仓库的状态检查，直接对指定或所有仓库执行pull操作，有一定风险，请慎重执行。 | | `--include-lock` | 指定该参数意味着同时也操作lock仓库。 | | `--continue` | MGit自定义参数，仅在操作多仓库过程中出现问题停止，执行状态进入中间态后可用。该参数只能单独使用，解决问题后可执行`mgit pull --continue`继续操作其余仓库。 | | `--abort` | MGit自定义参数，仅在操作多仓库过程中出现问题停止，执行状态进入中间态后可用。该参数用于清除操作中间态，且只能单独使用：`mgit pull --abort`。 | | `--help` | 显示帮助。 | 【注意】 1. 若指定了配置仓库，执行该指令时会先pull配置仓库，然后根据它内部的配置表pull其余仓库。 2. 执行时，会查看当前分支（如A）和远程分支（若有的话，如origin/A），只有当前分支（A）与远程分支（origin/A）出现落后或分叉的仓库才会执行指令。 3. 执行时，如果本地分支A和其跟踪的远程分支origin/A存在分叉，意味着执行pull之后会跟远程分支合并产生新节点，此时mgit会自动输入合法的log信息，并生成新提交。 4. 为了保证本地保存的远程分支（origin/A）为最新，执行前会先fetch一次。 5. 对于本地有异常的仓库，会提示执行操作，需要二次确认。 6. 执行前会校验各仓库分支是否统一。 7. 中间态：操作主仓库后如果导致配置文件冲突，会进入中间态。解决完冲突后，执行`mgit pull --continue`继续操作子仓库，或执行`mgit pull --abort`放弃本次操作。 ### push `mgit push [|--auto] [(--mrepo|--el-mrepo) ...] [--group-id] [--help]` | 特有参数 | 说明 | | ------------ | ------------------------------------------------------------ | | `--mrepo` | 指定需要执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。 | | `--el-mrepo` | 指定需要排除执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--el-mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。与`--mrepo`同时指定时无效。 | | `--group-id` | 指定一个group id，可将本次提交在远程做归类，若未指定则自动生成。生成的id将自动附加在url后：`mgit push --group-id = git push origin HEAD:refs/for/%topic=` | | `--help` | 显示帮助。 | 【注意】 1. 执行时会查看当前分支（如A）和远程分支（若有的话，如origin/A），只有当前分支（A）超前远程分支（origin/A）的仓库才会执行指令。注意，为了保证本地保存到远程分支（origin/A）为最新，执行前会先fetch一次。 2. 对于本地有异常的仓库，会提示执行操作（如`pull`指令描述所示）。 3. 执行前会校验各仓库分支是否统一。 ### rebase ``` mgit rebase [] [(--mrepo|--el-mrepo) ...] [--help] mgit rebase --continue mgit rebase --abort ``` | 特有参数 | 说明 | | ------------ | ------------------------------------------------------------ | | `--mrepo` | 指定需要执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。 | | `--el-mrepo` | 指定需要排除执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--el-mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。与`--mrepo`同时指定时无效。 | | `--continue` | MGit自定义参数，仅在操作多仓库过程中出现问题停止，执行状态进入中间态后可用。该参数只能单独使用，解决问题后可执行`mgit rebase --continue`继续操作其余仓库。 | | `--abort` | Git原生参数，用于取消`git rebase`中间态，但MGit做了增强，该参数可同时消除`mgit rebase`中间态，且只能单独使用：`mgit rebase --abort` | | `--help` | 显示帮助。 | 【注意】 1. 执行前会校验各仓库分支是否统一。 2. 该操作禁止使用`-i`和`--interactive`参数。 3. 中间态：同merge操作。 ### reset `mgit reset [] [(--mrepo|--el-mrepo) ...] [--help]` | 特有参数 | 说明 | | ------------ | ------------------------------------------------------------ | | `--mrepo` | 指定需要执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。 | | `--el-mrepo` | 指定需要排除执行该指令的仓库，可指定一个或多个，空格隔开，大小写均可，如：`--el-mrepo boxapp BBAAccount`，若缺省则对所有仓库执行指令。与`--mrepo`同时指定时无效。 | | `--help` | 显示帮助。 | 【注意】执行前会校验各仓库分支是否统一。 ### snap `mgit snap [-m |-r |-l] [-h]` 该指令用于根据当前多仓库状态生成快照，也可以从快照中恢复。 | 特有参数 | 说明 | | --------------- | ------------------------------------------------------------ | | `-r, --restore` | 从快照中恢复当前仓库，该操作执行前会清空所有未提交的仓库改动，请谨慎执行。用法：`mgit snap -r `。 | | `-l, --list` | 列出所有本地存储的快照。 | | `-m, --message` | 执行本次快照时附带的说明信息。用法：`mgit snap -m 'version x'`。 | | `-h, --help` | 显示帮助。 | ### stash `mgit stash [