GitPython git python 的开发库

工程地址: https://pypi.python.org/pypi/GitPython/
需要安装先安装: gitdb https://pypi.python.org/pypi/gitdb

GitPython使用模块对象访问git配置库。

仓库操作

    初始仓库对象

        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

    在操作大文件时，GitDB可以使用更少的内存，但处理速度慢2到5倍

    repo = Repo('path/to/repo',odbt=GitDB)

 

GitCmdObjectDB

    使用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