This documentation covers JsonGit’s interfaces.
JsonGit should be used through the public methods of Repository. You should use init() to obtain the object, not the constructor.
Obtain a Repository. Either a path to a repo or an existing pygit2.Repository must be provided. If the path exists, it will be interpreted as the path to an existing repository; if it does not, a new bare repository will be created there.
>>> repo = jsongit.init('path/to/repo')
Or, if you want to take advantage of special pygit2 options:
>>> import pygit2
>>> pygit_repo = pygit2.init_repository('path/to/repo', False)
>>> jsongit_repo = jsongit.init(repo=pygit_repo)
Parameters: |
|
---|---|
Returns: | A repository reference |
Return type: |
Add a value for a key to the working tree, staging it for commit.
>>> repo.add('added', 'but not committed!')
>>> repo.index('added')
u'but not committed!'
>>> repo.show('added')
KeyError: 'There is no key at added'
Parameters: |
|
---|---|
Raises : |
Replace the HEAD reference for dest with a commit that points back to the value at source.
>>> repo.commit('spoon', {'material': 'silver'})
>>> repo.checkout('spoon', 'fork')
>>> repo.show('fork')
{u'material': u'silver'}
Parameters: |
|
---|---|
Raises : |
Commit the index to the working tree.
>>> repo.add('foo', 'my very special bar')
>>> repo.commit()
>>> foo = repo.show('foo')
u'my very special bar'
If a key and value are specified, will add them immediately before committing them.
>>> repo.commit('fast', 'and easy, too!')
>>> foo = repo.show('fast')
u'and easy, too!'
Parameters: |
|
---|---|
Raises : |
Determine whether there is a commit for a key.
>>> repo.committed('foo')
False
>>> repo.commit('foo', 'bar')
>>> repo.committed('foo')
True
Parameters: | key (string) – the key to check |
---|---|
Returns: | whether there is a commit for the key. |
Return type: | boolean |
Erase this Git repository entirely. This will remove its directory. Methods called on a repository or its objects after it is destroyed will throw exceptions.
>>> repo.destroy()
>>> repo.commit('foo', 'bar')
AttributeError: 'NoneType' object has no attribute 'write'
Get the head commit for a key.
>>> repo.commit('foo', 'bar', message="leveraging fu")
>>> commit = repo.head('foo')
>>> commit.message
u'leveraging fu'
>>> commit.author.name
u'Jon Q. User'
>>> commit.time
1332438935L
Parameters: |
|
---|---|
Returns: | the data |
Return type: | int, float, NoneType, unicode, boolean, list, or dict |
Raises : | KeyError if there is no entry for key, IndexError if too many steps back are specified. |
Pull the current data for key from the index.
>>> repo.add('added', 'but not committed!')
>>> repo.index('added')
u'but not committed!'
Parameters: | key (string) – the key to get data for |
---|---|
Returns: | a value |
Return type: | None, unicode, float, int, dict, list, or boolean |
Traverse commits from the specified key or commit. Must specify one or the other.
>>> repo.commit('president', 'washington')
>>> repo.commit('president', 'adams')
>>> repo.commit('president', 'madison')
>>> log = repo.log('president')
>>> for commit in log:
... print(commit.data)
...
madison
adams
washington
Parameters: |
|
---|---|
Returns: | A generator to traverse commits, yielding :class:`Commit <jsongit.wrappers.Commit>`s. |
Return type: | generator |
Try to merge two commits together.
>>> repo.commit('spoon', {'material': 'silver'})
>>> repo.checkout('spoon', 'fork')
>>> repo.show('fork')
{u'material': u'silver'}
>>> repo.commit('spoon', {'material': 'stainless'})
>>> merge = repo.merge('fork', 'spoon')
>>> merge.message
u'Auto-merge of d0e0aa8061 and ce29b985cf from shared parent d21cb53771'
>>> repo.show('fork')
{u'material': u'stainless'}
Parameters: |
|
---|---|
Returns: | The results of the merge operation |
Return type: |
Remove the head reference to this key, so that it is no longer visible in the repo. Prior commits and blobs remain in the repo, but detached.
>>> repo.commit('foo', 'bar')
>>> repo.remove('foo')
>>> repo.committed('foo')
False
>>> repo.staged('foo')
False
Parameters: |
|
---|---|
Raises : | StagedDataError jsongit.StagedDataError |
Reset the value in the index to its HEAD value.
>>> repo.commit('creation', 'eons')
>>> repo.add('creation', 'seven days')
>>> repo.reset('creation')
>>> repo.index('creation')
u'eons'
Parameters: | key (string) – the key to reset |
---|
Obtain the data at HEAD, or a certain number of steps back, for key.
>>> repo.commit('president', 'washington')
>>> repo.commit('president', 'adams')
>>> repo.commit('president', 'madison')
>>> repo.show('president')
u'madison'
>>> repo.show('president', back=2)
u'washington'
Parameters: |
|
---|---|
Returns: | the data |
Return type: | int, float, NoneType, unicode, boolean, list, or dict |
Raises : | KeyError if there is no entry for key, IndexError if too many steps back are specified. |
Determine whether the value in the index differs from the committed value, if there is an entry in the index.
>>> repo.staged('huey')
False
>>> repo.add('huey', 'long')
>>> repo.staged('huey')
True
>>> repo.commit()
>>> repo.staged('huey')
False
Parameters: | key (string) – The key to check |
---|---|
Returns: | whether the entries are different. |
Return type: | boolean |
A wrapper around pygit2.Commit linking to a single key in the repo.
Returns: | The author of this commit. |
---|---|
Return type: | pygit2.Signature |
Returns: | The committer of this commit. |
---|---|
Return type: | pygit2.Signature |
Returns: | the data associated with this commit. |
---|---|
Return type: | Boolean, Number, None, String, Dict, or List |
Returns: | The unique 40-character hex representation of this commit’s ID. |
---|---|
Return type: | string |
Returns: | the key associated with this commit. |
---|---|
Return type: | string |
Returns: | The message associated with this commit. |
---|---|
Return type: | string |
Returns: | The unique 20-byte ID of this Commit. |
---|---|
Return type: | string |
Returns: | The repository of this commit. |
---|---|
Return type: | Repository |
Returns: | The time of this commit. |
---|---|
Return type: | long |
The repository provides an interface for merging. These classes provide methods and properties to investigate merges.
A class wrapper for the results of a merge operation.
The object that was merged in.
The message associated with this merge.
The original object.
Returns: | the object resulting from this merge, or None if there was a conflict. |
---|
Whether the merge was a success.
A class to encapsulate differences between two JSON git objects.
A dict of appended keys and their values.
Return an object modified with the changes in this diff.
Parameters: | original (list, dict, number, or string) – the object to apply the diff to. |
---|---|
Returns: | the modified object |
Return type: | list, dict, number, or string |
Determine whether a dict was produced by JSON diff.
A dict of removed keys and their values.
The diff is simply to replace wholesale.
A DiffWrapper
Raised when the requested global setting does not exist. Subclasses RuntimeError.
This is raised if a merge is attempted on a Commit in a different repo. Subclasses ValueError.
Raised when a non-string or invalid string is used as a key in a repository. Subclasses TypeError.
Raised when an object that cannot be run through json.dumps() is committed. Subclasses ValueError.
Raised when an attempt is made to remove a key that has data staged in the index. Subclasses RuntimeError
These are convenience methods used internally by JsonGit. They provide some useful abstractions for pygit2.
Convenience method to generate pygit2 signatures.
Parameters: |
|
---|---|
Returns: | a signature |
Return type: | pygit2.Signature |
Find the value of a git –global setting.
>>> jsongit.global_config('user.name')
'Jon Q. User'
>>> jsongit.global_config('user.email')
'jon.q@user.com'
Parameters: | name (string) – the name of the setting |
---|---|
Returns: | the value of the setting |
Return type: | string |
Raises : | NoGlobalSettingError |