pygwalk 0.2.1__tar.gz

pygwalk-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-2024 Zero <zero.kwok@foxmail.com>
+
+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.

pygwalk-0.2.1/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: pygwalk
+Version: 0.2.1
+Summary: gwalk 是一系列用于管理 Git 仓库的命令行小工具，帮助开发者对大批量的 Git 仓库进行日常维护。
+Author-email: Zero Kwok <zero.kwok@foxmail.com>
+License: MIT License
+Project-URL: Homepage, https://github.com/ZeroKwok/gwalk
+Project-URL: Issues, https://github.com/ZeroKwok/gwalk/issues
+Keywords: git,tools
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: GitPython
+Requires-Dist: termcolor
+Dynamic: license-file
+
+# gwalk
+
+`gwalk` 是一系列用于管理 Git 仓库的命令行小工具，帮助开发者对大批量的 Git 仓库进行日常维护。
+
+## 安装
+
+### 1. pip
+
+1. `python -m pip install pygwalk`
+
+### 2. build from source
+
+1. `git clone https://github.com/ZeroKwok/gwalk.git`
+2. `cd gwalk`
+3. `python -m pip install .`
+
+## 使用
+
+### 1. gl
+
+`gl.py` 是 `git pull` 操作的快捷工具。
+
+```bash
+# 从远程仓库拉取代码并合并到当前分支, 等价于下面的命令 
+# git pull {origin 或 第一个remotes} {当前分支}
+gl
+
+# git pull {origin 或 第一个remotes} {当前分支} --rebase
+gl --rebase
+```
+
+### 2. gcp
+
+`gcp.py` 是用于执行 `git commit` 和 `git push` 操作快捷工具。
+
+```bash
+# 添加未跟踪的文件以及已修改的文件，并提交到远程仓库, 等价于下面的命令 
+# git add -u && git commit -m "fix some bugs" && git push
+gcp "fix some bugs"
+
+# 仅推送当前分支到所有远程仓库，不进行提交
+gcp -p
+```
+
+### 3. gwalk
+
+`gwalk.py` 是 `gwalk` 工具的主要组件，提供了以下功能：
+
+- 列出目录下的所有 Git 仓库，支持过滤条件、黑名单、白名单和目录递归。
+- 显示列出的仓库的状态信息，支持输出信息的简短或冗长格式。
+- 在每个列出的仓库中执行一个操作。如运行自定义命令: 类似于子仓库操作 `git submodule foreach 'some command'` 但更加灵活。
+
+```bash
+# 列出当前目录下所有的'脏'的 Git 仓库
+gwalk
+
+# 递归列出当前目录下所有的 Git 仓库
+gwalk -rf all
+
+# 在列出的每个仓库中执行命令: git pull origin
+gwalk -rf all -a "run git pull origin"
+```
+
+## 使用技巧
+
+```bash
+# 在所有 gwalk 列出的仓库中, 执行 gl 工具(git pull)
+gwalk -rf all -a run gl
+
+# 在所有 gwalk 列出的仓库中, 执行 git push 操作 {ab} 表示 当前分支(ActiveBranch)
+gwalk -rf all -a run git push second {ab}
+
+# 批量手动处理(交互模式)
+# 在列出的所有 '包含未提交的修改' 的仓库中, 启动一个 bash shell 来接受用户的操作
+gwalk -rf modified --a bash
+
+# 批量推送
+# 在列出的所有 '包含未提交的修改 且 不再黑名单中' 的仓库中, 运行 gcp 工具, 推送当前分支到所有远程仓库
+gwalk -rf modified --blacklist gwalk.blacklist --a "gcp -p"
+
+# 批量打标签
+# 在列出的所有 白名单 gwalk.whitelist 匹配的仓库中, 运行 git tag v1.5.0
+gwalk -rf all --whitelist gwalk.whitelist -a run git tag v1.5.0
+
+# 批量查看目录下所有仓库的最近3次提交
+gwalk -f all -l none -a run "git log --oneline -n3"
+
+# 批量替换 origin 远程仓库的地址, 从 github.com 替换成 gitee.com
+# 在所有 gwalk 列出的仓库中, 执行自定义命令
+gwalk -rf all -a run git remote set-url origin `echo \`git remote get-url origin\` | python -c "print(input().replace('github.com', 'gitee.com'))"`
+```

pygwalk-0.2.1/README.md

@@ -0,0 +1,91 @@
+# gwalk
+
+`gwalk` 是一系列用于管理 Git 仓库的命令行小工具，帮助开发者对大批量的 Git 仓库进行日常维护。
+
+## 安装
+
+### 1. pip
+
+1. `python -m pip install pygwalk`
+
+### 2. build from source
+
+1. `git clone https://github.com/ZeroKwok/gwalk.git`
+2. `cd gwalk`
+3. `python -m pip install .`
+
+## 使用
+
+### 1. gl
+
+`gl.py` 是 `git pull` 操作的快捷工具。
+
+```bash
+# 从远程仓库拉取代码并合并到当前分支, 等价于下面的命令 
+# git pull {origin 或 第一个remotes} {当前分支}
+gl
+
+# git pull {origin 或 第一个remotes} {当前分支} --rebase
+gl --rebase
+```
+
+### 2. gcp
+
+`gcp.py` 是用于执行 `git commit` 和 `git push` 操作快捷工具。
+
+```bash
+# 添加未跟踪的文件以及已修改的文件，并提交到远程仓库, 等价于下面的命令 
+# git add -u && git commit -m "fix some bugs" && git push
+gcp "fix some bugs"
+
+# 仅推送当前分支到所有远程仓库，不进行提交
+gcp -p
+```
+
+### 3. gwalk
+
+`gwalk.py` 是 `gwalk` 工具的主要组件，提供了以下功能：
+
+- 列出目录下的所有 Git 仓库，支持过滤条件、黑名单、白名单和目录递归。
+- 显示列出的仓库的状态信息，支持输出信息的简短或冗长格式。
+- 在每个列出的仓库中执行一个操作。如运行自定义命令: 类似于子仓库操作 `git submodule foreach 'some command'` 但更加灵活。
+
+```bash
+# 列出当前目录下所有的'脏'的 Git 仓库
+gwalk
+
+# 递归列出当前目录下所有的 Git 仓库
+gwalk -rf all
+
+# 在列出的每个仓库中执行命令: git pull origin
+gwalk -rf all -a "run git pull origin"
+```
+
+## 使用技巧
+
+```bash
+# 在所有 gwalk 列出的仓库中, 执行 gl 工具(git pull)
+gwalk -rf all -a run gl
+
+# 在所有 gwalk 列出的仓库中, 执行 git push 操作 {ab} 表示 当前分支(ActiveBranch)
+gwalk -rf all -a run git push second {ab}
+
+# 批量手动处理(交互模式)
+# 在列出的所有 '包含未提交的修改' 的仓库中, 启动一个 bash shell 来接受用户的操作
+gwalk -rf modified --a bash
+
+# 批量推送
+# 在列出的所有 '包含未提交的修改 且 不再黑名单中' 的仓库中, 运行 gcp 工具, 推送当前分支到所有远程仓库
+gwalk -rf modified --blacklist gwalk.blacklist --a "gcp -p"
+
+# 批量打标签
+# 在列出的所有 白名单 gwalk.whitelist 匹配的仓库中, 运行 git tag v1.5.0
+gwalk -rf all --whitelist gwalk.whitelist -a run git tag v1.5.0
+
+# 批量查看目录下所有仓库的最近3次提交
+gwalk -f all -l none -a run "git log --oneline -n3"
+
+# 批量替换 origin 远程仓库的地址, 从 github.com 替换成 gitee.com
+# 在所有 gwalk 列出的仓库中, 执行自定义命令
+gwalk -rf all -a run git remote set-url origin `echo \`git remote get-url origin\` | python -c "print(input().replace('github.com', 'gitee.com'))"`
+```

pygwalk-0.2.1/gwalk/gapply.py

@@ -0,0 +1,83 @@
+#! python
+# -*- coding: utf-8 -*-
+#
+# This file is part of the gwalk project.
+# Copyright (c) 2020-2024 zero <zero.kwok@foxmail.com>
+#
+# For the full copyright and license information, please view the LICENSE
+# file that was distributed with this source code.
+#
+# gapply.py (git apply patch and create commit)
+#
+# Syntax:
+#   gapply.py [-h] <patch_file ...> 
+# 
+
+import os
+import re
+import sys
+from gwalk import gwalk
+
+def extract_subject_from_patch(patch_file):
+    with open(patch_file, 'r') as file:
+        lines = file.readlines()
+    for line in lines:
+        if line.startswith("Subject:"):
+            subject = line[len("Subject:"):].strip()
+            # Remove [PATCH X/Y] if it exists
+            subject = re.sub(r'\[PATCH [0-9]+/[0-9]+\] ', '', subject)
+            return subject
+    return None
+
+def extract_subject_from_filename(patch_file):
+    filename = os.path.splitext(os.path.basename(patch_file))[0]
+    subject = re.sub(r'^[0-9]+-', '', filename)
+    subject = re.sub(r'\.patch$', '', subject)
+    subject = subject.replace('-', ' ')
+    return subject
+
+def apply_patch(patch_file):
+    cmd = f'git apply -v "{patch_file}"'
+    gwalk.cprint(f'> {cmd}', 'green')
+    result = gwalk.RepoHandler.execute(cmd)
+    if result != 0:
+        gwalk.cprint(f"Failed to apply patch: {patch_file}", 'red')
+        sys.exit(result)
+
+def stage_changes():
+    cmd = f'git add -u'
+    gwalk.cprint(f'> {cmd}', 'green')
+    result = gwalk.RepoHandler.execute(cmd)
+    if result != 0:
+        gwalk.cprint(f"Failed to stage changes.", 'red')
+        sys.exit(result)
+
+def commit_changes(subject):
+    cmd = f'git commit -m "{subject}"'
+    gwalk.cprint(f'> {cmd}', 'green')
+    result = gwalk.RepoHandler.execute(cmd)
+    if result != 0:
+        gwalk.cprint(f"Failed to create commit.", 'red')
+        sys.exit(result)
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: gapply.py <patch_file ...>")
+        sys.exit(1)
+
+    for patch_file in sys.argv[1:]:
+        if not os.path.isfile(patch_file):
+            gwalk.cprint(f"Patch file {patch_file} does not exist", 'red')
+            sys.exit(1)
+
+        subject = extract_subject_from_patch(patch_file)
+        if not subject:
+            subject = extract_subject_from_filename(patch_file)
+
+        apply_patch(patch_file)
+        stage_changes()
+        commit_changes(subject)
+
+
+if __name__ == "__main__":
+    main()

pygwalk-0.2.1/gwalk/gcp.py

@@ -0,0 +1,91 @@
+#! python
+# -*- coding: utf-8 -*-
+#
+# This file is part of the gwalk project.
+# Copyright (c) 2020-2024 zero <zero.kwok@foxmail.com>
+#
+# For the full copyright and license information, please view the LICENSE
+# file that was distributed with this source code.
+#
+# gcp.py (git commit and push)
+#
+# 语法
+#   gcp.py [-h] [-a|--all] [--show] [-p|--push] [-s|--src <SRC>] ["提交信息"]
+# 
+# 示例
+#   1. gcp.py "fix some bugs"
+#      仅推送当前分支到所有远端, 不做提交
+#      相当于执行: git add -u && git commit -m "提交信息" && git push {remotes} {branch}
+#   2. gcp.py --push
+#      仅推送当前分支到所有远端, 不做提交
+#
+# 选项
+#   --show      仅显示执行命令，而不做任何改变
+#   -a,--all    添加未跟踪的文件以及已修改的文件
+#   -s,--src    要推送的本地仓库中的 分支 或 标签
+#   -p,--push   仅执行推送动作, 将忽略 --all 以及 commit
+#   commit      提交消息
+
+import os
+import argparse
+from gwalk import gwalk
+
+class ResultError(RuntimeError):  
+    def __init__(self, message, ecode):  
+        super().__init__(message)  
+        self.ecode = ecode  
+
+def execute(commands:str, onlyShow:bool=False):
+   gwalk.cprint(commands, 'green')
+   if onlyShow:
+      return
+   code = gwalk.RepoHandler.execute(commands)
+   if code != 0:
+      raise ResultError(f'Run: {commands}', code)
+
+def main():
+   try:
+      parser = argparse.ArgumentParser()
+      parser.add_argument('-a', '--all', action='store_true')
+      parser.add_argument('-s', '--src', action='store', default=None)
+      parser.add_argument('-p', '--push', action='store_true')
+      parser.add_argument('--show', action='store_true')
+      parser.add_argument('commit', nargs=argparse.REMAINDER)
+      args = parser.parse_args()
+
+      args.commit = ' '.join(args.commit)
+
+      if not gwalk.RepoWalk.isRepo(os.getcwd()):
+         gwalk.cprint(f'This is not an valid git repository.', 'red')
+         exit(1)
+
+      repo = gwalk.RepoStatus(os.getcwd()).load()
+
+      if args.src is None:
+         args.src = repo.repo.active_branch.name
+
+      if args.push:
+         for r in repo.repo.remotes:
+            execute(f'git push {r.name} {args.src}', args.show)
+         exit(0)
+
+      if repo.match('clean'):
+         gwalk.cprint(f'The git repository is clean.', 'green')
+         exit(0)
+      execute('git status -s --untracked-files=normal')
+
+      if repo.match('dirty' if args.all else 'modified'):
+         execute('git add -A' if args.all else 'git add -u', args.show)
+         if args.commit:
+            execute(f'git commit -m "{args.commit}"', args.show)
+         else:
+            execute(f'git commit', args.show)
+         for r in repo.repo.remotes:
+            execute(f'git push {r.name} {args.src}', args.show)
+      exit(0)
+   except ResultError as e:
+      exit(e.ecode)
+
+
+if __name__ == '__main__':
+   main()

pygwalk-0.2.1/gwalk/gl.py

@@ -0,0 +1,40 @@
+#! python
+# -*- coding: utf-8 -*-
+#
+# This file is part of the gwalk project.
+# Copyright (c) 2020-2024 zero <zero.kwok@foxmail.com>
+#
+# For the full copyright and license information, please view the LICENSE
+# file that was distributed with this source code.
+
+import os
+import argparse
+from gwalk import gwalk
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--rebase', action='store_true')
+    args = parser.parse_args()
+
+    if not gwalk.RepoWalk.isRepo(os.getcwd()):
+        gwalk.cprint(f'This is not an valid git repository.', 'red')
+        exit(1)
+
+    repo   = gwalk.git.Repo(os.getcwd())
+    branch = repo.active_branch.name
+    remote = 'origin'
+    if not remote in repo.remotes:
+        if len(repo.remotes) > 0:
+            remote = repo.remotes[0].name
+
+    rebase = ''
+    if args.rebase:
+        rebase = '--rebase'
+    
+    cmd = f'git pull {remote} {branch} {rebase}'
+    gwalk.cprint(f'> {cmd}', 'green')
+    exit(gwalk.RepoHandler.execute(cmd))
+
+
+if __name__ == '__main__':
+    main()

pygwalk-0.2.1/gwalk/gwalk.py

@@ -0,0 +1,547 @@
+#! python
+# -*- coding: utf-8 -*-
+#
+# This file is part of the gwalk project.
+# Copyright (c) 2020-2024 zero <zero.kwok@foxmail.com>
+#
+# For the full copyright and license information, please view the LICENSE
+# file that was distributed with this source code.
+#
+# gwalk.py
+#
+# 功能性需求
+# - 列出指定目录下的所有的Git仓库
+#   - 可指定过滤条件
+#     - 存在未提交的修改
+#     - 存在未跟踪的文件
+#     - 脏的: 存在未提交的修改 或 未跟踪的文件 (默认)
+#     - 所有
+#   - 可指定黑名单, 即跳过匹配的仓库
+#   - 可指定白名单, 即列出匹配的仓库
+#   - 可指定是否递归搜索目录
+# - 显示列出仓库的状态信息
+#   - 可指定输出信息是简短还是冗长
+# - 指定在每个列出的仓库中执行的任务
+#   - run CMD
+#     在仓库中执行命令: CMD
+#   - git gui
+#     在仓库中唤起: Git Gui 
+#   - git bash
+#     在仓库中唤起: Git Bash
+#
+# 语法
+#   gwalk.py [--help][--version]  [--verbose | --level LEVEL]
+#            [--directory PATH]   [--recursive] [--blacklist FILENAME] [--force]
+#            [--filter CONDITION] [--action PROC]
+# 示例
+#   1. gwalk.py
+#      列出当前目录下所有'脏'的Git仓库(不包含./gwalk.blacklist黑名单文件中匹配的项)
+#   2. gwalk.py -f  all -r
+#      gwalk.py -rf all
+#      递归列出当前目录下所有的Git仓库(不包含./gwalk.blacklist黑名单文件中匹配的项)
+#   3. gwalk.py -rf all -a run git pull origin
+#      在列出的每个仓库中执行命令: git pull origin
+#
+# 选项
+#   -h,--help       显示帮助信息
+#   --version       输出程序版本
+#   --debug         启用调试输出, 辅助调试过滤条件与执行的命令
+#
+#   -v,--verbose    列出仓库的同时, 还会输出尽可能详细的状态信息
+#   -l,--level      指定输出等级
+#       'none'        仅列出仓库, 不打印仓库状态
+#       'brief'       列出仓库的同时, 还会输出只有一行的简短信息(默认)
+#       'normal'      列出仓库的同时, 还会输出一般的仓库的状态信息
+#       'verbose'     同--verbose
+#
+#   -d,--directory  指定目录下搜索Git仓库, 默认是程序的当前目录
+#   -r,--recursive  指定是否进入子文件夹, 从而列出尽可能多的仓库
+#   -f,--filter     指定搜索仓库的过滤条件, 只有满足条件的仓库将被列出
+#       'all'         所有仓库
+#       'clean'       所有'干净'的仓库
+#       'dirty'       所有'脏'的仓库(默认)
+#       'modified'    所有'包含未提交的修改'的仓库
+#       'untracked'   所有'包含跟踪文件的修改'的仓库
+#   --blacklist     指定黑名单文件, 若黑名单文件有效, 则将忽略所有匹配的仓库, 即使指定了
+#                   --condition=all.
+#                   黑名单采用正则表达式匹配仓库目录的绝对路径 (分隔符统一为: '/' Unix filesystem分隔符)
+#                   示例如下:
+#                     ^.+/3rd$
+#                     ^.+/demo$
+#                   若--blacklist未指定, 则尝试在--directory指定的目录下查找 gwalk.blacklist文件.
+#
+#   --whitelist     指定白名单文件, 使黑名单机制失效. 若白名单文件有效, 则将忽略所有未匹配的仓库.
+#   --force         使黑名单机制失效, 即使指定了--blacklist
+#
+#   -a,--action     指定在每个列出的仓库中执行的任务
+#       'gui'         在每个列出的仓库唤出 Git Gui  来处理用户的操作
+#       'bash'        在每个列出的仓库唤出 Git Bash 来处理用户的操作
+#       'run CMD'     在每个列出的仓库执行 CMD 指定的命令, 可以在命令中包含下列"变量"(不区分大小写), 
+#                      这将在执行前被替换为相应的内容.
+#                        {ab} 或 {ActiveBranch} 将被替换为当前仓库的 活动分支名
+#                        {RepositoryName}       将被替换为当前仓库的 目录名
+#                        {cwd}                  将被替换为 --directory 指定的目录, 因为 . 是当前仓库的目录.
+
+import os
+import re
+import sys
+import shutil
+import argparse
+import platform
+import traceback
+
+projectName    = 'gwalk'
+projectHome    = 'https://github.com/ZeroKwok/gwalk.git'
+projectVersion = '0.2.1'
+projectAuthor  = 'zero.kwok@foxmail.com'
+
+try:
+    import git
+    from   termcolor import cprint
+except ModuleNotFoundError as e:
+    print(f'{projectName} depends on "GitPython" and "termcolor", use the following command to install them:')
+    print()
+    print('"python -m pip install GitPython termcolor"')
+    exit(1)
+except KeyboardInterrupt:
+    exit(1)
+
+class RepoWalk:
+    def __init__(self, directory:str, recursive:bool=False, debug:bool=False):
+        self.directory = directory
+        self.recursive = recursive
+        self.debug = debug
+
+    def __iter__(self):
+        if self.recursive:
+            for root, dirs, files in os.walk(self.directory):
+                if RepoWalk.repoType(dirs, files) != 0:
+                    yield root
+        else:
+            for root, dirs, files in os.walk(self.directory):
+                if RepoWalk.isRepo(root):
+                    yield root
+                for d in dirs:
+                    if d in ['.git', '.vs', '.vscode']:
+                        continue
+                    path = os.path.normpath(os.path.join(root, d))
+                    if RepoWalk.isRepo(path):
+                        yield path
+                break
+
+    def repoType(dirs, files) -> int:
+        '''0 None, 1 Normal, 2 Submodule'''
+        if '.git' in dirs:
+            return 1
+        if '.git' in files:
+            return 2
+        return 0
+
+    def isRepo(directory) -> int:
+        for _, dirs, files in os.walk(directory):
+            return RepoWalk.repoType(dirs, files) != 0
+        return False
+
+# 参考文档
+# - [GitPython doc](https://gitpython.readthedocs.io/en/stable/)
+# - [How to manage git repositories with Python](https://linuxconfig.org/how-to-manage-git-repositories-with-python)
+class RepoStatus:
+    def __init__(self, directory:str):
+        self.repo = git.Repo(directory)
+        self.status = []
+
+    class AssetState:
+        def __init__(self, x = '', y = '', path = ''):
+            self.X = x
+            self.Y = y
+            self.PATH = path
+            self.ORIG_PATH = None
+
+        def match(self, condition:str='dirty') -> bool:
+            '''
+            condition: 
+              - dirty: 存在未提交 或 未跟踪的内容
+              - modified: 存在未提交的修改
+              - untracked: 存在未跟踪的文件
+            '''
+            
+            '''
+            XY可能出现的值:  
+              - ' ' = unmodified
+              - 'M' = modified
+              - 'A' = added
+              - 'D' = deleted
+              - 'R' = renamed
+              - 'C' = copied
+              - 'U' = updated but unmerged
+
+            X          Y     Meaning
+            -------------------------------------------------
+                     [AMD]   not updated
+            M        [ MD]   updated in index
+            A        [ MD]   added to index
+            D                deleted from index(git rm)
+            R        [ MD]   renamed in index(git mv)
+            C        [ MD]   copied in index
+            [MARC]           index and work tree matches
+            [ MARC]     M    work tree changed since index
+            [ MARC]     D    deleted in work tree
+            [ D]        R    renamed in work tree
+            [ D]        C    copied in work tree
+            -------------------------------------------------
+            D           D    unmerged, both deleted
+            A           U    unmerged, added by us
+            U           D    unmerged, deleted by them
+            U           A    unmerged, added by them
+            D           U    unmerged, deleted by us
+            A           A    unmerged, both added
+            U           U    unmerged, both modified
+            -------------------------------------------------
+            ?           ?    untracked
+            !           !    ignored
+            -------------------------------------------------
+            '''
+
+            flags = 0
+            if not self.X in ' ?' or self.Y in 'MD':
+                flags = 1 
+            elif self.X == '?' and self.Y == '?':
+                flags = 2 
+
+            if condition == 'modified':
+                return flags == 1
+            elif condition == 'untracked':
+                return flags == 2
+            elif condition == 'dirty':
+                return flags != 0
+            else:
+                raise RuntimeError(f'Invalid parameter: condition={condition}')
+
+    def __bool__(self):
+        '''返回True, 表示仓库状态是脏的(dirty)'''
+        return bool(self.status)
+    
+    def load(self):
+        '''
+        加载仓库状态
+        '''
+
+        '''
+        相当于执行下面的命令: 
+        git status --porcelain=1 --untracked-files=normal
+    
+        参考:
+        https://git-scm.com/docs/git-status
+        https://git-scm.com/docs/git-status#_output
+
+        Short Format:
+        - XY PATH
+        - XY ORIG_PATH -> PATH
+
+        XY 是两个字符的状态码, ORIG_PATH 只在 重命名 或 复制 时显示.
+
+        XY 语法有三种不同模式的状态:
+            - 一般模式: 即当合并成功或在合并之外的情况, X表示index的状态, Y表示工作树的状态.
+            - 合并模式: 即当发生合并冲突且尚未解决时, X和Y表示相对于共同的祖先, 两个HEAD所引入的状态, PATH 表示未合并.
+            - 未跟踪模式: 即当PATH是未跟踪的文件时, X与Y总是相同的, 因为它们index是未知的. 
+            忽略的文件不会被列出, 除非使用--ignored; 如果是，则忽略的文件将用!!表示。
+        '''
+        self.status = []
+
+        # porcelain       易于解析的简单的输出, 类似-s(Short Format)
+        # untracked_files 包含详细的未跟踪文件列表
+        #   - normal - Shows untracked files and directories.
+        #   - all - Also shows individual files in untracked directories.
+        #   - no - Show no untracked files.
+        proc = self.repo.git.status(porcelain='1', untracked_files='normal', as_process=True)
+
+        # XY PATH
+        # XY ORIG_PATH -> PATH
+        for line in proc.stdout:
+            line = line.decode('utf-8').rstrip('\n')
+            if len(line) == 0:
+                continue
+
+            asset = self.AssetState()
+            asset.X = line[0:1]
+            asset.Y = line[1:2]
+            asset.PATH = line[3:]
+
+            if ' -> ' in asset.PATH:
+                match = re.search(r'^"?(.+?)"? -> "?(.+?)"?$', asset.PATH)
+                if match is None:
+                    raise RuntimeError('Unexpected format: ' + line)
+                asset.PATH = match.group(2)
+                asset.ORIG_PATH = match.group(1)
+            elif asset.PATH[0] == '"' and asset.PATH[-1] == '"':
+                asset.PATH = asset.PATH[1:-2]
+            self.status.append(asset)
+        proc.wait()
+        return self
+
+    def match(self, condition:str='dirty') -> bool:
+        '''
+        condition: 
+          - modified: 存在未提交的修改
+          - untracked: 存在未跟踪的文件
+          - dirty: 存在modified或untracked
+          - clean: 不存在modified或untracked
+        '''
+        if condition == 'all':
+            return True
+        elif condition == 'clean':
+            return not self
+        elif condition == 'dirty':
+            return bool(self)
+
+        for asset in self.status:
+            if asset.match(condition):
+                return True
+        return False
+
+    def display(self, root:str, level:str='brief'):
+        dir = self.repo.working_dir
+        dir = os.path.relpath(self.repo.working_dir, root)
+
+        if level == 'none':
+            cprint(dir)
+            return
+
+        cprint(dir, 'green', end=' ')
+        cprint(f'({self.repo.active_branch.name})', 'cyan')
+
+        if level == 'brief':
+            modified = []
+            untracked = []
+            for item in self.status:
+                if not item.X in ' ?' or item.Y in 'MD':
+                    modified.append(item)
+                elif item.X == '?' and item.Y == '?':
+                    untracked.append(item)
+
+            if not modified and not untracked:
+                cprint(f'  Clean', 'white')
+            else:
+                cprint(f'  Modified: {len(modified)}, Untracked: {len(untracked)}', 'red')
+
+        else:
+            lastcwd = os.getcwd()
+            try:
+                os.chdir(self.repo.working_dir)
+                if level == 'normal':
+                    os.system('git status -s --untracked-files=normal --ignore-submodules=all')
+                else:
+                    os.system('git status -b --show-stash --untracked-files=all --ignore-submodules=all --ignored')
+            finally:
+                os.chdir(lastcwd)
+
+class RepoHandler:
+    def __init__(self):
+        self.success = []
+        self.failure = []
+        
+    def execute(cmd:str) -> int:
+        code = os.system(cmd)
+        if platform.system().lower() != 'windows':
+            code >>= 8
+        return code
+    
+    def perform(self, repo, args):
+        lastcwd = os.getcwd()
+        try:
+            if args.action == 'bash':
+                cprint('')
+                cprint(f'> Note that you are running in a new bash...', 'yellow')
+                cprint(f'> * Press "CTRL + D" to exit the bash!', 'yellow')
+                cprint(f'> * Press "CTRL + C, CTRL + D" to abort the {projectName}!', 'yellow')
+                os.chdir(repo.repo.working_dir)
+                os.system('bash')
+
+            elif args.action == 'gui':
+                os.chdir(repo.repo.working_dir)
+                os.system('git gui')
+
+            elif args.action == 'run':
+                cmd = ' '.join(args.params)
+                if '{ab}' in cmd:
+                    cmd = cmd.replace('{ab}', repo.repo.active_branch.name)
+                if '{ActiveBranch}' in cmd:
+                    cmd = cmd.replace('{ActiveBranch}', repo.repo.active_branch.name)
+                if '{RepositoryName}' in cmd:
+                    cmd = cmd.replace('{RepositoryName}', os.path.basename(repo.repo.working_dir))
+                if '{cwd}' in cmd:
+                    cmd = cmd.replace('{cwd}', args.directory)
+
+                os.chdir(repo.repo.working_dir)
+                repo.code = RepoHandler.execute(cmd)
+                if args.debug:
+                    cprint(f'> Execute: {cmd} -> {repo.code}', 'red' if repo.code else 'yellow')
+                if repo.code == 0:
+                    self.success.append(repo)
+                else:
+                    self.failure.append(repo)
+                    
+        except Exception as e:
+            traceback.print_exc()
+
+        finally:
+            os.chdir(lastcwd)
+
+    def report(self, prefix:str=''):
+        if self.success or self.failure:
+            return prefix + f'Run result: success {len(self.success)}, failure {len(self.failure)}'
+        else:
+            return ''
+
+class PathFilter:
+    def __init__(self, filename:str=None) -> None:
+        self.patterns = None
+        self.filename = filename
+        self.load(filename)
+
+    def __bool__(self):
+        return self.patterns is not None
+
+    def load(self, filename:str) -> bool:
+        if not filename:
+            return
+        self.patterns = []
+        with open(filename, 'r') as f:
+            for line in f:
+                line = line.lstrip(' ').rstrip('\n')
+                if not line or line.startswith('#'):
+                    continue
+                self.patterns.append(re.compile(line.rstrip('\n')))
+
+    def match(self, path) -> bool:
+        path = path.replace('\\', '/')
+        for item in self.patterns:
+            if item.match(path):
+                return True
+        return False
+
+def cli():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--version', action='store_true')
+    parser.add_argument('--debug',  action='store', nargs='?', default='disabled')
+
+    parser.add_argument('-v', '--verbose', action='store_true', default=False)
+    parser.add_argument('-l', '--level', action='store', choices=['none', 'brief', 'normal', 'verbose'], default='brief')
+
+    parser.add_argument('-d', '--directory', action='store', default=os.getcwd())
+    parser.add_argument('-r', '--recursive', action='store_true', default=False)
+
+    parser.add_argument('-f', '--filter', action='store', choices=['all', 'clean', 'dirty', 'modified', 'untracked'], default='dirty')
+    parser.add_argument('--blacklist', action='store', default='')
+    parser.add_argument('--whitelist', action='store', default='')
+    parser.add_argument('--force', action='store_true')
+
+    parser.add_argument('-a', '--action', action='store', choices=['bash', 'gui', 'run'], default=None)
+    parser.add_argument('params', nargs=argparse.REMAINDER)
+
+    args = parser.parse_args()
+    
+    mapping = {'disabled' : '', None : 'enabled'}
+    if args.debug in mapping:
+        args.debug = mapping[args.debug]
+    if args.debug:
+        print(f'> {projectName} args={args}')
+    if 'wait' in args.debug:
+        input('Wait for debugging and press Enter to continue...')
+
+    if args.version:
+        print(f'{projectName} version {projectVersion} powered by {projectAuthor}')
+        print(f'Home: {projectHome}')
+        exit(0)
+
+    # --verbose 优先
+    if args.verbose:
+        args.level = 'verbose'
+
+    # 观察
+    args.untracked_files = 'normal'
+    if args.level == 'verbose':
+        args.untracked_files = 'all'
+
+    args.directory = args.directory.strip(' \'"')
+    args.blacklist = args.blacklist.strip(' \'"')
+    args.whitelist = args.whitelist.strip(' \'"')
+
+    if args.blacklist and not os.path.exists(args.blacklist):
+        raise RuntimeError(f'Invalid blacklist: {args.blacklist}')
+    if args.whitelist and not os.path.exists(args.whitelist):
+        raise RuntimeError(f'Invalid whitelist: {args.whitelist}')
+    if not args.blacklist and os.path.exists(f'{projectName}.blacklist'):
+        args.blacklist = f'{projectName}.blacklist'
+
+    # 如果白名单被指定, 则使黑名单失效, 类似: --force
+    if args.whitelist: 
+        args.force = True
+    if args.force:
+        args.blacklist = ''
+    args.whitelist = PathFilter(args.whitelist)
+    args.blacklist = PathFilter(args.blacklist)
+    if args.debug:
+        cprint(f'> Blacklist: ' + (f'Valid {{{args.blacklist.filename}}}' if args.blacklist else 'Invalid'), 'yellow')
+        cprint(f'> Whitelist: ' + (f'Valid {{{args.whitelist.filename}}}' if args.whitelist else 'Invalid'), 'yellow')
+
+    ignored = 0
+    matched = 0
+    handler = RepoHandler()
+    for path in RepoWalk(args.directory, args.recursive, debug=args.debug):
+        def filter(list, name, reverse=False):
+            '''
+            返回True表示被忽略, 黑名单匹配的项应该忽略, 而白名单匹配的项则反之, 名单未初始化则不参与过滤.
+            matched : reverse 的组合结果如下: 
+                1 : 0 = 1
+                0 : 0 = 0
+                1 : 1 = 0
+                0 : 1 = 1
+            '''
+            
+            if not list:
+                return False
+            matched = list.match(path)
+            if args.debug:
+                if 'trace' in args.debug:
+                    cprint(f'> {name}.match({path}): {matched}', 'yellow' if matched else 'white')
+                if matched ^ reverse:
+                    cprint(f'> ignored repo that {"not in" if reverse else "in"} {name}: {os.path.relpath(path, args.directory)}', 'yellow')
+            return matched ^ reverse
+        
+        if filter(args.blacklist, 'blacklist') or filter(args.whitelist, 'whitelist', True):
+            ignored += 1
+            continue
+
+        repo = RepoStatus(path)
+        if not (args.filter == 'all' and args.level == 'none'):
+            repo.load()
+        if not repo.match(args.filter):
+            ignored += 1
+            if args.debug:
+                cprint(f'> ignored repo that not match filter "{args.filter}": {os.path.relpath(path, args.directory)}', 'yellow')
+            continue
+
+        matched += 1
+        repo.display(args.directory, args.level)
+        handler.perform(repo, args)
+
+    cprint('')
+    cprint(f'Walked {matched+ignored} repo, matched: {matched}, ignored: {ignored}{handler.report("; ")}', 
+            'red' if handler.failure else 'white')
+    
+    if handler.failure:
+        cprint('The failed projects are as follows:', 'red')
+        for repo in handler.failure:
+            cprint(' - ' + os.path.relpath(repo.repo.working_dir, args.directory), 'red')
+
+
+def main():
+    try:
+        cli()
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == '__main__':
+    main()

pygwalk-0.2.1/pygwalk.egg-info/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: pygwalk
+Version: 0.2.1
+Summary: gwalk 是一系列用于管理 Git 仓库的命令行小工具，帮助开发者对大批量的 Git 仓库进行日常维护。
+Author-email: Zero Kwok <zero.kwok@foxmail.com>
+License: MIT License
+Project-URL: Homepage, https://github.com/ZeroKwok/gwalk
+Project-URL: Issues, https://github.com/ZeroKwok/gwalk/issues
+Keywords: git,tools
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: GitPython
+Requires-Dist: termcolor
+Dynamic: license-file
+
+# gwalk
+
+`gwalk` 是一系列用于管理 Git 仓库的命令行小工具，帮助开发者对大批量的 Git 仓库进行日常维护。
+
+## 安装
+
+### 1. pip
+
+1. `python -m pip install pygwalk`
+
+### 2. build from source
+
+1. `git clone https://github.com/ZeroKwok/gwalk.git`
+2. `cd gwalk`
+3. `python -m pip install .`
+
+## 使用
+
+### 1. gl
+
+`gl.py` 是 `git pull` 操作的快捷工具。
+
+```bash
+# 从远程仓库拉取代码并合并到当前分支, 等价于下面的命令 
+# git pull {origin 或 第一个remotes} {当前分支}
+gl
+
+# git pull {origin 或 第一个remotes} {当前分支} --rebase
+gl --rebase
+```
+
+### 2. gcp
+
+`gcp.py` 是用于执行 `git commit` 和 `git push` 操作快捷工具。
+
+```bash
+# 添加未跟踪的文件以及已修改的文件，并提交到远程仓库, 等价于下面的命令 
+# git add -u && git commit -m "fix some bugs" && git push
+gcp "fix some bugs"
+
+# 仅推送当前分支到所有远程仓库，不进行提交
+gcp -p
+```
+
+### 3. gwalk
+
+`gwalk.py` 是 `gwalk` 工具的主要组件，提供了以下功能：
+
+- 列出目录下的所有 Git 仓库，支持过滤条件、黑名单、白名单和目录递归。
+- 显示列出的仓库的状态信息，支持输出信息的简短或冗长格式。
+- 在每个列出的仓库中执行一个操作。如运行自定义命令: 类似于子仓库操作 `git submodule foreach 'some command'` 但更加灵活。
+
+```bash
+# 列出当前目录下所有的'脏'的 Git 仓库
+gwalk
+
+# 递归列出当前目录下所有的 Git 仓库
+gwalk -rf all
+
+# 在列出的每个仓库中执行命令: git pull origin
+gwalk -rf all -a "run git pull origin"
+```
+
+## 使用技巧
+
+```bash
+# 在所有 gwalk 列出的仓库中, 执行 gl 工具(git pull)
+gwalk -rf all -a run gl
+
+# 在所有 gwalk 列出的仓库中, 执行 git push 操作 {ab} 表示 当前分支(ActiveBranch)
+gwalk -rf all -a run git push second {ab}
+
+# 批量手动处理(交互模式)
+# 在列出的所有 '包含未提交的修改' 的仓库中, 启动一个 bash shell 来接受用户的操作
+gwalk -rf modified --a bash
+
+# 批量推送
+# 在列出的所有 '包含未提交的修改 且 不再黑名单中' 的仓库中, 运行 gcp 工具, 推送当前分支到所有远程仓库
+gwalk -rf modified --blacklist gwalk.blacklist --a "gcp -p"
+
+# 批量打标签
+# 在列出的所有 白名单 gwalk.whitelist 匹配的仓库中, 运行 git tag v1.5.0
+gwalk -rf all --whitelist gwalk.whitelist -a run git tag v1.5.0
+
+# 批量查看目录下所有仓库的最近3次提交
+gwalk -f all -l none -a run "git log --oneline -n3"
+
+# 批量替换 origin 远程仓库的地址, 从 github.com 替换成 gitee.com
+# 在所有 gwalk 列出的仓库中, 执行自定义命令
+gwalk -rf all -a run git remote set-url origin `echo \`git remote get-url origin\` | python -c "print(input().replace('github.com', 'gitee.com'))"`
+```

pygwalk-0.2.1/pygwalk.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+gwalk/__init__.py
+gwalk/gapply.py
+gwalk/gcp.py
+gwalk/gl.py
+gwalk/gwalk.py
+pygwalk.egg-info/PKG-INFO
+pygwalk.egg-info/SOURCES.txt
+pygwalk.egg-info/dependency_links.txt
+pygwalk.egg-info/entry_points.txt
+pygwalk.egg-info/requires.txt
+pygwalk.egg-info/top_level.txt
+tests/test_gwalk.py

pygwalk-0.2.1/pygwalk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pygwalk-0.2.1/pygwalk.egg-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+gapply = gwalk.gapply:main
+gcp = gwalk.gcp:main
+gl = gwalk.gl:main
+gwalk = gwalk.gwalk:main

pygwalk-0.2.1/pygwalk.egg-info/requires.txt

@@ -0,0 +1,2 @@
+GitPython
+termcolor

pygwalk-0.2.1/pygwalk.egg-info/top_level.txt

@@ -0,0 +1 @@
+gwalk

pygwalk-0.2.1/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pygwalk"
+authors = [{ name = "Zero Kwok", email = "zero.kwok@foxmail.com" }]
+description = "gwalk 是一系列用于管理 Git 仓库的命令行小工具，帮助开发者对大批量的 Git 仓库进行日常维护。"
+keywords = ["git", "tools"]
+readme = "README.md"
+requires-python = ">=3.7"
+license = {text = "MIT License"}
+classifiers = [
+    # How mature is this project? Common values are
+    #   3 - Alpha
+    #   4 - Beta
+    #   5 - Production/Stable
+    "Development Status :: 5 - Production/Stable",
+
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Build Tools",
+
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+]
+dependencies = [
+    "GitPython",
+    "termcolor",
+]
+dynamic = ["version"]
+
+[tool.setuptools.dynamic]
+version = {attr = "gwalk.gwalk.projectVersion"}
+
+[project.urls]
+Homepage = "https://github.com/ZeroKwok/gwalk"
+Issues = "https://github.com/ZeroKwok/gwalk/issues"
+
+[project.scripts]
+gl = "gwalk.gl:main"
+gcp = "gwalk.gcp:main"
+gwalk = "gwalk.gwalk:main"
+gapply = "gwalk.gapply:main"

pygwalk-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pygwalk-0.2.1/tests/test_gwalk.py

@@ -0,0 +1,42 @@
+import os
+import pytest
+from gwalk.gwalk import RepoStatus, PathFilter
+
+class TestRepoStatus:
+    def test_asset_state_match(self):
+        """测试 AssetState.match() 方法"""
+        state = RepoStatus.AssetState('M', 'M', 'test.txt')
+        assert state.match('modified') == True
+        assert state.match('untracked') == False
+        assert state.match('dirty') == True
+
+        state = RepoStatus.AssetState('?', '?', 'test.txt')
+        assert state.match('modified') == False
+        assert state.match('untracked') == True
+        assert state.match('dirty') == True
+
+        state = RepoStatus.AssetState(' ', ' ', 'test.txt')
+        assert state.match('modified') == False
+        assert state.match('untracked') == False
+        assert state.match('dirty') == False
+
+class TestPathFilter:
+    def test_path_filter_match(self, tmp_path):
+        """测试 PathFilter.match() 方法"""
+        # 创建临时的黑名单文件
+        blacklist = tmp_path / "test.blacklist"
+        blacklist.write_text("""
+# 注释行
+^.+/test1$
+^.+/test2$
+""")
+        
+        filter = PathFilter(str(blacklist))
+        assert filter.match('path/to/test1') == True
+        assert filter.match('path/to/test2') == True
+        assert filter.match('path/to/test3') == False
+
+    def test_path_filter_empty(self):
+        """测试空的 PathFilter"""
+        filter = PathFilter(None)
+        assert bool(filter) == False