GitPython git python 的开发库

初始仓库对象
from git import *
repo = Repo(repo_path)
assert repo.bare == False

创建裸库
repo = Repo.init(repo_path,bare=True)
assert repo.bare == True

仓库数据高层接口可以新增/删除 heads/tags/remotes和访问仓库的配置信息
repo.config_reader() #获得仓库中只读的配置信息
repo.config_writer() #更新仓库中的配置信息

获取活动分支、未被管理的文件和判断是否有变更
repo.is_dirty()  #返回布尔值
repo.untracked_files    #返回未被管理的文件列表

克隆和初始化一个新的仓库
cloned_repo = repo.clone(to/this/path)
new_repo = repo.init(path/for/new/repo)

repo对象的性能优于数据库对象，repo对象一般用于获取大数据和新增对象。

在操作大文件时，GitDB可以使用更少的内存，但处理速度慢2到5倍
repo = Repo('path/to/repo',odbt=GitDB)

使用git-cat-file实例读取配置库信息，访问速度比较快，但内存占用比GitDB严重。
repo = Repo('path/to/repo',odbt=GitCmdObjectDB)

head操作
heads = repo.heads
master = heads.master #lists can be accessed by name for convenience
master.commit #the commit pointed to by head called master
master.rename('new_name') #rename heads
tag(tag通常是不变的)是一个commit或tag对象的引用
tags = repo.tags
tagref = tags[0] #tag可以有一个tag对象，存储额外的信息
tagref.commit #tag总是指向一个commit
repo.delete_tag(tagref) #删除一个tag
repo.create_tag('my_tag') #创建一个tag
符号引用可以替代具体commit指向一个引用
head = repo.head        #the head points to the active branch/ref
master = head.reference #but they always point to commits
master.commit   #from here you use it as any other reference

访问reflog
log = master.log()
log[0]  #first reflog entry
log[-1] #last reflog entry
修改引用
创建、删除各种引用和修改指向
repo.delete_head('master') #delete an existing head
master = repo.create_head('master')  #create a new one
master.commit = 'HEAD~10'   #set branch to another commit without changing index or working tree
创建、删除tags
new_tag = repo.create_tag('my_tag','my message')
repo.delete_tag(new_tag)
分支直接切换
new_branch = repo.craete_head('new_branch')
repo.head.reference = new_branch

git库的各种对象
git的所有对象都存在git数据库中。对象包含的信息有类型、未压缩的大小、每个对象都有一个20个字节的唯一的SHA1值。
git有四类对象Blobs、Trees、Commits and Tags
git所有的对象都可以访问，但通常是通过引用或git仓库的方法来访问，不是直接从数据库中读取。
hc = repo.head.commit
hct = hc.tree
hc != hct
hc != repo.tags[0]
hc == repo.head.reference.commit
git对象基本字段有
hct.type
hct.size
hct.hexsha
hct.binsha
索引对象可以用作git的索引，这些对象是Trees/Blobs和Submodules ,这些对象含有文件路径的信息。
hct.path    #root tree has no path
hct.trees[0].path #the first subdirectory has one though
hct.mode    #trees have the mode of a linux directory
hct.blobs[0].mode #blobs have a specific mode though compareable to a standard linux fs
使用stream访问blob数据或者其他对象数据
hct.blobs[0].data_stream.read() #stream object to read data from
hct.blobs[0].stream_data(open("blob_data","w")) #write data to given stream

Commit对象
commit对象包含固定commit的信息。通过引用或者指定版本可以获取到commit对象
repo.commit('master')
repo.commit('v0.1')
repo.commit('HEAD~10')
获取100指定引用上100commit
repo.iter_commits('master',max_count=100)
分页显示
显示21-30的记录
repo.iter_commits('master',max_count=10,skip=20)

headcommit = repo.head.commit
headcommit.hexsha
headcommit.parents
headcommit.author
headcommit.tree
headcommit.committer
headcommit.committed_date
headcommit.message
时间格式化
import time
time.asctime(time.gmtime(headcommit.committed_date))  #'Web May 7 05:56:02 2013'
tiem.strftime("%a,%d %b %Y %H:%M",time.gmtime(headcommit.committed_date)) #'Web,7 May 2013 05:56'
访问commit祖先
headcommit.parents[0].parents[0].parents[0].parents[0]
等价于master^^^^ 或者master~4

Tree对象
tree对象指向当前目录的内容。获取master分支最新提交的根tree对象
tree = repo.heads.master.commit.tree
通过tree对象可以获取的内容有
tree.trees  #trees are subdirectories
tree.blobs  #blobs are files
可以通过名称获取tree对象
tree[0] = tree['dir']  #access by index and by sub-path
blob = tree[0][0]
blob.name
blob.path
blob.abspath
有简便的方法通过子目录名称就可以获取对象
tree/"lib"
tree/"dir/file" == blob
如果指定tree对象的名称也可以直接从git数据库中读取
repo.tree() #返回<git.Tree "master">
repo.tree("c1c7214dde86...")
repo.tree('0.1.6')
遍历tree对象
tree.traverse()
for entry in tree.traverse():do_something_with(entry)
如果tree对象返回的是子模块对象，默认为是当前head的commit

索引对象
git的索引对象包含了commit变更和合并信息。通过索引对象可以获得更复杂的信息
index = repo.index
读取、添加、删除实例，Commit变更:
for stage,blob in index.iter_blobs():do_something(...)  #Access blob object
for (path,stage),entry in index.entries.iteritems: pass #Access the entries directly
index.add(['my_new_file'])   #add a new file to the index
index.remove(['dir/existing_file'])
new_commit = index.commit("my commit message")
通过tree或者merge创建新索引
tmp_index = Index.from_tree(repo,'HEAD~1') #load a tree into a temporary index
merge_index = Index.from_tree(repo,'base','HEAD','some_branch') #merge two trees three-way
merge_index.write('merged_index')
远程仓库
远程名称作为外部从仓库的别名，可以通过它push和fetch数据
test_remote = repo.create_remote('test','git@server:repo.git')
repo.delete_remote(test_remote) # create and delete remotes
origin = repo.remotes.origin #get default remote by name
origin.refs  #local remote reference
o = origin.rename('new_origin') #rename remotes
o.fetch()   #fetch,pull and push from and to the remote
o.pull()
o.push()
远程库的配置信息
o.url
修改配置信息
o.config_writer.set('pushurl','other_url')
子模块

对象比较
可以比较index和Trees或者Index和working tree 或者trees和trees以及trees和working copy
hcommit = repo.head.commit
idiff = hcommit.diff()  #diff tree against index
tdiff = hcommit.diff('HEAD~1')  #diff tree against previous tree
wdiff = hcommit.diff(None)  #diff tree against working tree

index = repo.index
index.diff() #diff index agginst itself yielding empty idff
index.diff(None) #diff index against working copy
index.diff('HEAD') #diff index against current HEAD tree
比较返回的比较索引本质上是一个Diff对象列表，通过额外的过滤方法你可以找到你想要的内容
for diff_added in wdiff.iter_change_type('A'): do_something_with(diff_added)

分支切换
想切换分支，你需要设置HEAD指向新分支，重置index和工作区
repo.head.reference = repo.heads.other_branch
repo.head.reset(index=True,working_tree=True)
上面的方法会覆盖掉工作区中所有修改未提交的边更新，下面的方法则不会
repo.heads.master.checkout() #checkout the branch using git-checkout
repo.heads.other_branch.checkout()
直接使用git库
通过git实例使用git命令
git = repo.git
git.checkout('head',b='my_new_branch')  #default command
git.for_each_ref()  #'-' becomes '_' when calling it