使用Gitlab来管理文档(git共享编辑)、共享已有经验(wiki)。
- 什么是git
详见百度百科:Git
Git是一个开源的分布式版本控制系统,可以有效、高速地处理从很小到非常大的项目版本管理。Git 是 Linus Torvalds 为了帮助管理 Linux 内核开发而开发的一个开放源码的版本控制软件。
Github和Gitlab是比较成熟等git服务提供商,其Web版编辑器比较完善,并且对中文友好,比国内厂商领先不少。
我们是要拿git当作一个支持全文搜索和文件名搜索、带wiki、有本地备份的网盘使用,用于共享公司内部文档和经验。
- 为什么不自己搭git服务器
Gitlab.com免费,并且访问相对畅通,支持私有项目,没有必要自己搭建、运维一套git。 由于git在本地始终有一套备份,甚至wiki词条实际上也能通过git访问和编辑,所以只要服务提供商和本地数据不同时出问题,就没有问题。
- 为什么使用Gitlab.com
Gitlab.com可以免费创建私有项目(不允许未授权用户访问)。Gitlab基于Web的界面相对成熟,便于简单查看和编辑,支持wiki因此很适合分享知识。
Gitlab每个月允许群组进行2000(分钟*用户)的同步操作,只要不频繁大幅度修改非文本文件,git会自动差分,一般足够。
国内上传文件速度大约能到2M/s以上,因此速度不用担心。
- 为什么不使用Github
Github免费版私有项目现在只支持3个协作者,并且wiki需要额外付费。
- 为什么要注册Github账号
Gitlab注册需要使用Google的验证码服务,国内无法访问。但是可以通过Github账号登陆,然后设置密码,这样同名账号就可以在Gitlab使用了。
此外,Github有带图形界面的git客户端,比其他客户端方便得多。
-
如何分享、查找知识点
Gitlab支持全文+文件搜索,一般使用wiki和文档(以及代码)进行分享。
wiki一般适用于零散的专项信息,例如常见或偶发问题的解决、单个或一组名词解释等。
文档一般适用于系统性的描述,例如API文档、产品文档、加工流程等。
-
哪些文档可以共享
理论上任意文档只要不是太大都可以共享(建议小于100M,否则会影响同步时间、占用项目容量),包括word、excel、源代码、图片、压缩包等。
对于需要协作的文档,建议使用Markdown格式文本或者纯文本格式(txt、csv等)进行编辑,这样只使用web版就能编辑,也便于全文检索。
- 什么是Markdown格式
一种简单的标记语言,文件扩展名为.md,可以很容易的转为HTML页面。在Gitlab上,默认会以HTML模式显示其内容。
Markdown语法见Markdown基本语法 如果懒得去学,直接使用纯文本也可以正常识别的,只需要换段落时多打一个回车。再有心情一些,在几级标题前打几个#号这样就能直接识别为章节生成链接。
VSCode、Eclipse、EditPlus甚至最简单的文本编辑器都可以用来编辑Markdown文件,在线的编辑器界面更友好一些,适合简单编辑。本地编辑器效率更高一些,工作量较大时容易保存和编辑。
Github桌面客户端适用于Windows和Mac OS,界面简单易用、全集成面配置,可以访问Github之外的git服务(建议使用基于HTTPS的服务)。首次安装时可能要登陆Github账号。
访问Github,右上角有Sign up
按钮,点击后打开注册页面。
然后填写账号(Username)、邮箱(Email address)、密码(Password),然后在下边的验证码区域(Verify account)通过验证,点击最下边的Create account
即可注册。由于密码要求较高,之后可能经常要查收邮件激活、找回密码,因此可以使用自己常用邮箱注册,最后统一上报即可。
之后进入选择账号类型的页面(Choose your plan),当然选择Free
,然后点下方的Continue
按钮。
之后是兴趣偏好调查(Welcome to GitHub),直接点最下方Submit
按钮即可。
然后进入自己的主页,选择Start a project
按钮,会要求先验证邮箱。收邮件,点邮件里的Verify
按钮或链接,即可激活并访问Github。此时就可以创建工程了。当然这里只是注册账号而已。
打开Gitlab登陆页面,右侧切换至Sign in
页签,选择github
账号登陆,然后一路同意授权即可完成登陆。
然后在右上角的设置按钮的下拉菜单(向下的小箭头)中,选择Settings
,打开设置页面。在页面左侧选择密码设置(Password),设上密码然后Save即可。
如果需要中文菜单,在Settings
页面左侧选择账户设置(Profile),将Preferred language
设为简体中文然后保存即可。
到这里,就可以用自己Github邮箱在Gitlab登陆了。
私有项目的文件必须登陆并且账号被管理员添加到项目组中才能访问。 这里不对项目、工程、仓库、repo这些名词进行细分,认为是工程即可
Gitlab
页面上方有一个+
,点击后可以新建项目(以及用户群组)。
项目有私有、内部、公开三个级别,其中内部指的是Gitlab.com所有账号都可以访问,所以一般是选择私有(仅授权用户可见)以及公开(用于直接共享可向公司外部公开的文档)。
这里主要指添加可以访问和编辑项目文档的人。
打开项目后(在项目列表中点击某个项目,或者直接打开该项目的任意文件或Wiki),页面左侧就变为项目设置菜单栏。展开最下方的设置
菜单,展开后选择其中的成员
菜单,然后可以邀请用户(支持邮箱或者账号搜索)或者组加入该项目。
权限分为:
- Guest,访客,只能简单看看、提交问题(issue)和评论,不能下载代码、修改工程内容
- Reporter,访客全部权限,外加可以下载代码但是不能提交修改
- Developer,开发者,Reporter全部权限外加允许提交代码修改,可以创建Wiki
- Maintainer,维护者,不能改名删除项目、不能删除Gitlab页面、不能删除问题、不能修改调整保护分支。其余权限都有
- Owner,就是创建工程的人,啥都可以干
权限都有有效期设置。文档管理可以宽松些,给Developer及更高权限(Owner一般不给)。
在Gitlab
上,当已经打开一个工程后,点击左侧的仓库
(repo)菜单栏里的设置
菜单(和展开后选择其中的通用
菜单效果相同)进入工程设置页面。最下方有一个Advanced
菜单组,点击其右侧的展开
(expand)菜单即可找到重命名、删除项目这些重量级操作。
-
Web版:访问工程主页,如果有权限就能访问。
-
github客户端:
工程(的文档)和wiki都可以使用HTTPS方式进行访问,使用
File
->Clone repository
菜单打开git服务访问页面,切换至URL
页签,填写访问地址然后选择本地路径开始Clone
即可。连接时要登陆账号。文档的地址为:
https://gitlab.com/工程创建账号/工程名.git
wiki的地址为:
https://gitlab.com/工程创建账号/工程名.wiki.git
文档和wiki的阅读者一般只需要使用web版
文档的主要编辑者建议连接到git而不是使用web版
wiki一般只需要负责备份的人连接即可。
工程的Wiki(Web版,查看时更好用)一般在
https://gitlab.com/工程创建账号/工程名/wikis/home
,登陆后可访问,已有Wiki列表在右侧。
有时候使用全文检索更快捷,Gitlab
页面右上方有检索栏。
在工程中建立Wiki页面(左下角菜单栏里的wiki
菜单)即可。点击左侧Wiki菜单后,打开的默认是创建新Wiki的页面,当然右侧也有已有Wiki列表,可以查看或编辑。
似乎在线编辑时插入图片或其他文件十分方便,可以直接attach a file
。
点击左侧Wiki菜单后,右侧会列出已有Wiki,点击打开后可以可以看到编辑
和页面历史
菜单。
Web版页面上方直接就有搜索栏,支持含Wiki在内的全文/文件名综合检索(因此建议使用纯文本分享经验)。点击搜索结果中的文件名即可打开相应文件页面。
怎样支持组合检索谁知道请修改这里
文档都有一个永久链接(Permalink)供直接访问,.md文件支持直接预览,当然私有项目的文档得登陆并且有访问权限才能看。
可以对外公开的文档,建议另建立公开工程进行分享,文件直接从涉及的私有工程汇总拷贝。
尚不知道有没有允许个别文件公开的设定方法,如果有更方便
待完善
- 建议文档名称包含主版本号,主版本升级新建文档