taitava/silverstripe-assetcommitter

立即将上传的 SilverStripe 资产文件提交到版本控制系统（VCS）仓库。

维护者

详细信息

github.com/Taitava/silverstripe-assetcommitter

源代码

问题

安装: 0

依赖项: 0

建议者: 0

安全: 0

星标: 0

关注者: 2

分支: 1

开放问题: 2

类型:silverstripe-module

dev-master 2020-01-14 20:50 UTC

Requires

MIT e533990afc555ed73d03c6299e3e8fdbed7dd7f9

fileassetsassetgitrepositoryfilespushsilverstripecommit

This package is auto-updated.

Last update: 2024-09-15 07:12:03 UTC

README

所以，你的 SilverStripe assets 目录在生产服务器和开发机器上的内容不同，你希望使用 VCS 来同步它们？或者你只是想将 assets 作为应急计划备份到 VCS 中？这个模块就是为了这个设计的：它通过监听 File 类的钩子自动提交上传/删除/重命名的 assets 目录文件。它还可以推送到远程仓库。但它不会从远程仓库拉取/合并，这需要手动完成。

只要它是 git，你可以使用任何你想要的版本控制系统。

未来会支持其他 VCS 吗？没有计划，但如果会，将需要其他开发者的努力（欢迎 Pull Requests），因为目前我只熟悉 git。但该模块的设计方式使得引入其他 VCS 系统也很容易。

要求

  • SilverStripe 框架 3.0.0 或更高版本（CMS 不需要）
  • czproject/git-php 3.17.1 或更高版本（如果你使用 composer，会自动安装）

安装与配置

  1. 安装模块：composer require taitava/silverstripe-assetcommitter

  2. 如果你的 assets 目录还没有初始化 git 仓库，请先初始化： cd assets && git init（我强烈建议你为你的资产使用一个专用的仓库——不要将其与存储项目源代码文件的仓库混合）。此外，运行 git config user.email "default@email.address" && git config --global user.name "Default User"。这是为了提供一个默认的 作者 名称和电子邮件地址，以便在模块无法确定 author 时使用。模块将使用已登录用户的电子邮件和姓名（通过调用带有 --author 参数的 git commit）覆盖 author，但如果没有人登录，将使用默认的 author。

  3. 确保你的 web 服务器有权限写入 assets/.git！

  4. 通过 YAML 配置进行最终微调

GitAssetCommitter:
  repository_path: 'assets' # This should point to the 'assets' directory (which should be your repository's root directory.)
  push_to_after_committing: false # If you want commit's to be pushed to a remote repository, set this to a string like "origin master" or just "origin", otherwise set this to false.
  automatically_define_author: true # If true, the currently logged in CMS user's email and name will be used as an author of commits. If nobody is logged in, the default author of the repository will be used.
  supplement_empty_author_email: 'cms.user@localhost' # If a logged in user does not have an email address, use this instead. Has no effect if automatically_define_author is false.
  supplement_empty_author_name: 'CMS User' # If a logged in user does not have a name, use this instead. Has no effect if automatically_define_author is false.
  commit_file_creations: true
  commit_file_deletions: true
  commit_file_renamings: true # Also affects movings
  
AssetCommitterFactory:
  committer_class: GitAssetCommitter # If you want to write a custom class that should handle committing, define the fully qualified name of the class here. Most of the time you will not want to change this value. Note that you may need to copy the above configuration values and apply them to your new class in your YAML config file!
  1. 记得在浏览器中运行 ?flush=all 来清除缓存！

通过钩子扩展

目前有两个钩子可以用来自定义该模块的行为

  • updateGitCommitMessage()
  • updateGitCommitAuthor()

要使用这些钩子，你需要创建两个文件。在 mysite/_config/assetcommitter.yml 中创建一个新的文件（如果存在则追加）

GitAssetCommitter:
  extensions:
    - MyGitAssetCommitterExtension

然后，在 mysite/code/MyGitAssetCommitterExtension.php 中创建一个新的 PHP 类

class MyGitAssetCommitterExtension extends Extension
{
	/**
	 * @param string $action Either 'create', 'replace', 'rename', or 'delete'. Tells what we are doing. Not meant to be modified in the hook method.
	 * @param string $commit_message The default message generated by `assetcommitter`. Set your new message to this variable.
	 */
	public function updateGitCommitMessage($action, &$commit_message)
	{
		$commit_message = 'My superior commit message must be present in every commit! And here is the type of the committed event: '.$action;
	}

	/**
	 * @param string $action Either 'create', 'replace', 'rename', or 'delete'. Tells what we are doing. Not meant to be modified in the hook method.
	 * @param string $author The default author generated by `assetcommitter`. Set your new author name and email to this variable in this format: "Firstname Surname <email.address@somewhere.tld>". If you wish to unset the author completely, set this to null.
	 */
	public function updateGitCommitAuthor($action, &$author)
	{
		$author = 'It\'s me! ALWAYS ME! <donald.trump@whitehouse.gov>';
	}
}

最后，记得在浏览器中运行 ?flush=all 来清除缓存！

哲学

这个模块非常简单，仍在建设中。实际上：我甚至没有真实世界的项目会用到这个模块。至少目前还没有。我做这个只是出于好奇 :)。这意味着你应该知道这个模块还没有在任何真实网站/应用程序中测试过，因此它可能包含一些尚未被注意到的问题，因为缺乏使用/测试。

现在，上面的事情已经讲过了，让我们来看看这个模块 确实做了什么 和 没有做什么

它做了什么

  • 该模块会提交新的资产文件、资产文件的删除以及资产文件的重命名/移动。如果你只想添加文件而不希望从仓库中删除它们，每种类型都可以单独禁用。
  • 您可以配置它自动将更改推送到远程仓库，但这不是强制性的。
  • 它监听SilverStripe的File类中的钩子。它不会扫描文件系统中的更改。因此，旧文件不会得到提交。

它不做的事情

  • 它不会为您初始化git仓库。因此，您应该在终端中运行： cd assets && git init 并配置默认的作者。
  • 分支。它不会创建它们，也不会检出它们。它始终停留在当前分支，无论是什么。
  • 拉取/合并。不，因为它无法处理合并冲突。并且因为它需要它还必须为拉取的新文件创建数据库记录（并编辑拉取的已重命名/移动文件的记录）。在没有极客监督的情况下做这件事太冒险了。
  • 修改SilverStripe数据库中的任何内容。不会创建表或添加列。没有运行时写入，所以您数据库中的数据应该保持完整。但如果您的数据库仍然损坏，请请请别跑到我的办公室来。
  • 它不能用于存储资产的目录之外的任何目录。它只是不通过扫描文件系统来检测任何更改。

重要提示

  • Git是一个复杂的东西。请准备好不时检查您的仓库，看看是否正常：工作目录应该是干净的，分支应该是您想要的分支，推送应该工作，不应该有未跟踪的文件（.gitignore它们）。如果出了问题，那就是您自己要修复！ :)
  • 如果远程分支包含本地分支中不存在的提交，推送将失败。换句话说：提交可以工作，但所有提交都只会保留在本地仓库中，如果文件系统损坏或有人偷走了您的自酿服务器，所有的“已提交”资产都会丢失，因为它们没有被推送到远程仓库。所以请确保您在远程仓库中为这些自动提交指定一个特定的分支，只有一个服务器/机器会推送这些自动提交！任何活着的极客都不应该在那个分支上提交任何东西 - 或者如果他们真的做了，他们应该去运行这个模块的机器/服务器上，从远程拉取更改。
  • 您应该为您的assets文件夹创建一个新的仓库，该仓库与项目的源代码分开。三个原因：1) 如果模块搞坏了仓库，我不想在门口遇到愤怒的程序员告诉我他们失去了多少公里的心爱代码。2) 如果远程仓库包含本地仓库中没有的提交，自动推送将无法工作（除非您使用单独的分支）。3) 您需要将您的web服务器用户（即www-data或apache）对仓库目录中的.git目录的写权限。
  • 请参阅下面的TODO & BUGS部分以获取当前问题。

问题

未捕获的GitException：命令'git ...'失败（退出代码128）

请注意，三个点只是一个替代品，以替换您遇到此问题时将获得的更具体的错误消息。

您可能缺少对仓库中.git目录的写权限。请确保您的web服务器有权限写入该目录。

但这不是这个错误消息总是出现的原因。不幸的是，czproject/git-php不会报告git发出的原始错误消息（至少czproject/git-php版本3.17.1是这样的）。有关进一步参考，请参阅czproject/git-php问题#47

我已定制库（通过扩展GitRepository类和GitException异常）以向GitException添加更多信息。您应该在异常的message中看到“命令输出：”部分，其中包含git命令的描述性错误消息。

我还提交了一个拉取请求，将我的改进应用到原始库中。如果它被合并，我将从这个模块中移除我的自定义。

如何为命令提供用户名和密码

This section is copied on 2020-01-14 from [czproject/git-php README.md](https://github.com/czproject/git-php/blob/b5e709f0e9c4e4e39b49d4e322f7fa73c1bb21dc/readme.md).

> 1. use SSH instead of HTTPS - https://stackoverflow.com/a/8588786
> 2. store credentials to Git Credential Storage
>    http://www.tilcode.com/push-github-without-entering-username-password-windows-git-bash/
>    https://help.github.com/articles/caching-your-github-password-in-git/
>    https://git-scm.cn/book/en/v2/Git-Tools-Credential-Storage
> 3. insert user and password into remote URL - https://stackoverflow.com/a/16381160
>    git remote add origin https://user:password@server/path/repo.git
> 4. NOT IMPLEMENTED IN THIS MODULE: for push() you can use --repo argument - https://stackoverflow.com/a/12193555
>    $git->push(NULL, array('--repo' => 'https://user:password@server/path/repo.git'));

待办事项 & 缺陷

针对1.0版本

  • 处理文件覆盖。我不确定现在是如何处理的，它是否会首先执行删除提交，然后执行创建提交？请参阅问题 #2。

可以稍后完成

  • 使能够使用assets子目录作为存储库的根目录。请参阅问题 #4。
  • 创建一个可以运行以初始化git存储库的BuildTask。这也会设置存储库的默认作者。
  • 创建一个可以运行以检查git存储库是否可以正确访问（存在且可写）的BuildTask。

维护者联系方式

Jarkko Linnanvirta jarkko (at) taitavasti (dot) fi（英文或芬兰语）