1 /**
  2  * @fileOverview This is just an empty file containing JSDoc markup to generate nice documentation for stuff that is actually implemented in C++.
  3  * @author Sam Day
  4  * @version 0.1.0
  5  */
  6 
  7 /**
  8  * Represents an open Git repository. The majority of the functionality offered 
  9  * by Gitteh is contained in here.
 10  * @class
 11  */
 12 var Repository = function() {};
 13 
 14 /**
 15  * This is the namespace of the Gitteh module.
 16  * @namespace
 17  * @example
 18  * var gitteh = require("gitteh");
 19  */
 20 var Gitteh = { };
 21 
 22 /**
 23  * Opens a Git repository at the location provided. You can either provide a
 24  * path to a Git repository, which will open the repository "bare" (no working
 25  * directory), or you can provide an object containing paths to the various 
 26  * critical Git directories needed for Git to operate.
 27  * @param {String|Object} path
 28  * @param {String} path.gitDirectory The path to the Git repository folder (e.g /foo/.git)
 29  * @param {String} [path.workTree] The path to the Git working directory (e.g /foo). Omitting this will assume the repository is bare.
 30  * @param {String} [path.objectDirectory] The path to the ODB directory (e.g /foo/.git/objects). Omitting this will default to path.gitDirectory + "/objects"
 31  * @param {String} [path.indexFile] The path to the repository index file (e.g /foo/.git/index). Omitting this will default to path.gitDirectory + "/index"
 32  * @param {Function} [callback] If provided, the repository will be opened asynchronously, and the provided callback will be fired when the repository has been opened.
 33  * @returns {Repository}
 34  * @throws If the path provided is incorrect, or the repository is corrupt in some way. 
 35  */
 36 Gitteh.openRepository = function(path) { };
 37 
 38 /**
 39  * Creates a new Git repository at the provided path. The repository will be
 40  * created at the path provided, unless bare is set to true, in which case the 
 41  * repository will be initialized in a <i>.git</i> directory inside the path
 42  * provided.
 43  * @param {String} path The path to initialize the new Git repository in.
 44  * @param {Boolean} [bare] Initialize the repository as bare or "checked out".
 45  * @param {Function} [callback] If provided, the repository will be created asynchronously. The provided callback will be fired when the repository has been created.
 46  */
 47 Gitteh.initRepository = function(path, bare, callback) { };
 48 
 49 /**
 50  * Contains the various error constants found throughout Gitteh.
 51  * @namespace
 52  */
 53 Gitteh.error = { };
 54 
 55 // Ffs. There's supposed to be a JSDoc "metatag" that allows me to define one
 56 // set of tags and it will apply to everything that follows. It doesn't work.
 57 // Hence the bullshit here.
 58 /**
 59  * @static
 60  * @constant
 61  */
 62 Gitteh.error.GIT_SUCCESS = undefined;
 63 /**
 64  * @static
 65  * @constant
 66  */
 67 Gitteh.error.GIT_ERROR = undefined;
 68 /**
 69  * @static
 70  * @constant
 71  */
 72 Gitteh.error.GIT_ENOTOID = undefined;
 73 /**
 74  * @static
 75  * @constant
 76  */
 77 Gitteh.error.GIT_ENOTFOUND = undefined;
 78 /**
 79  * @static
 80  * @constant
 81  */
 82 Gitteh.error.GIT_ENOMEM = undefined;
 83 /**
 84  * @static
 85  * @constant
 86  */
 87 Gitteh.error.GIT_EOSERR = undefined;
 88 /**
 89  * @static
 90  * @constant
 91  */
 92 Gitteh.error.GIT_EOBJTYPE = undefined;
 93 /**
 94  * @static
 95  * @constant
 96  */
 97 Gitteh.error.GIT_EOBJCORRUPTED = undefined;
 98 /**
 99  * @static
100  * @constant
101  */
102 Gitteh.error.GIT_ENOTAREPO = undefined;
103 /**
104  * @static
105  * @constant
106  */
107 Gitteh.error.GIT_EINVALIDTYPE = undefined;
108 /**
109  * @static
110  * @constant
111  */
112 Gitteh.error.GIT_EMISSINGOBJDATA = undefined;
113 /**
114  * @static
115  * @constant
116  */
117 Gitteh.error.GIT_EPACKCORRUPTED = undefined;
118 /**
119  * @static
120  * @constant
121  */
122 Gitteh.error.GIT_EFLOCKFAIL = undefined;
123 /**
124  * @static
125  * @constant
126  */
127 Gitteh.error.GIT_EZLIB = undefined;
128 /**
129  * @static
130  * @constant
131  */
132 Gitteh.error.GIT_EBUSY = undefined;
133 /**
134  * @static
135  * @constant
136  */
137 Gitteh.error.GIT_EBAREINDEX = undefined;
138 /**
139  * @static
140  * @constant
141  */
142 Gitteh.error.GIT_EINVALIDREFNAME = undefined;
143 /**
144  * @static
145  * @constant
146  */
147 Gitteh.error.GIT_EREFCORRUPTED = undefined;
148 /**
149  * @static
150  * @constant
151  */
152 Gitteh.error.GIT_ETOONESTEDSYMREF = undefined;
153 /**
154  * @static
155  * @constant
156  */
157 Gitteh.error.GIT_EPACKEDREFSCORRUPTED = undefined;
158 /**
159  * @static
160  * @constant
161  */
162 Gitteh.error.GIT_EINVALIDPATH = undefined;
163 /**
164  * @static
165  * @constant
166  */
167 Gitteh.error.GIT_EREVWALKOVER = undefined;
168 /**
169  * @static
170  * @constant
171  */
172 Gitteh.error.GIT_EINVALIDREFSTATE = undefined;
173 /**
174  * @static
175  * @constant
176  */
177 Gitteh.error.GIT_ENOTIMPLEMENTED = undefined;
178 
179 /**
180  * Retrieves a {@link Commit} from the repository with the given sha1 hash id.
181  * @param {String} sha1 The sha1 hash ID of the commit.
182  * @param {Function} [callback] If callback is provided, Vommit will be retrieved asynchronously and passed to to the callback provided.
183  * @return {Commit}
184  * @throws If commit wasn't found, or there is some other error. 
185  */
186 Repository.prototype.getCommit = function(sha1, callback) {};
187 
188 /**
189  * Creates a new Commit and immediately stores it in the Repository.
190  * @param {Object} data The data for the commit. Should be the same properties that a {@link Commit} contains.
191  * @param {Function} [callback] If provided, the Commit will be created asynchronously, and the newly created Commit object returned to the callback.
192  * @throws If Commit couldn't be created.
193  */
194 Repository.prototype.createCommit = function(data, callback) {};
195 
196 /**
197  * Retrieves a {@link Tree} from the repository with the given sha1 hash id.
198  * @param {String} sha1 The sha1 hash ID of the tree.
199  * @param {Function} [callback] If a callback is provided, the Tree will be retrieved asynchronously and returned via the callback given.
200  * @return {Tree}
201  * @throws If Tree wasn't found, or some other error occurs. 
202  */
203 Repository.prototype.getTree = function(sha1, callback) {};
204 
205 /**
206  * Creates a new {@link Tree} in the Repository with the given data. <b>NOTE:</b>
207  * this is currently unimplemented.
208  * @param {Object} data
209  * @param {Function} [callback]
210  */
211 Repository.prototype.createTree = function(data, callback) {};
212 
213 /**
214  * Retrieves a {@link Reference} from the Repository with the given name.
215  * @param {String} name The name of the reference, for example: refs/heads/master. You may also retrieve <i>HEAD</i> using this method.
216  * @param {Function} [callback] If provided, the reference will be obtained asychronously, and provided to the callback.
217  * @return {Reference}
218  * @throws If Reference does not exist, or some other error occured. 
219  */
220 Repository.prototype.getReference = function(name, callback) {};
221 
222 /**
223  * Creates a new OID (direct) {@link Reference} in the Repository.
224  * @param {String} name The name of the Reference to be created.
225  * @param {String} oid The ID of the {@link Commit} being pointed to.
226  * @param {Function} [callback] When provided, the Reference shall be created asynchronously. The callback will be notified when creation is complete.
227  * @returns {Reference}
228  * @throws If there was an error creating the Reference.
229  */
230 Repository.prototype.createOidReference = function(name, oid, callback) {};
231 
232 /**
233  * Creates a new symbolic (indirect) {@link Reference} in the Repository.
234  * @param {String} name The name of the Reference to be created.
235  * @param {String} target The name of the Reference being pointed to.
236  * @param {Function} [callback] When provided, the Reference shall be created asynchronously. The callback will be notified when creation is complete.
237  * @returns {Reference}
238  * @throws If there was an error creating the Reference.
239  */
240 Repository.prototype.createSymbolicReference = function(name, target, callback) {};
241 
242 /**
243  * Requests a list of References from the Repository. This will return a list of
244  * Strings, each String is a name of a reference in the Repository.
245  * @param {Integer} [flags] If provided, the list will be filtered based on input. Valid values are {@link Gitteh.GIT_REF_OID}, {@link Gitteh.GIT_REF_SYMBOLIC}, {@link Gitteh.GIT_REF_PACKED}, and {@link Gitteh.GIT_REF_LISTALL}
246  * @param {Function} [callback] If provided, the list will be built asynchronously, and the results provided to the callback.
247  * @returns {String[]}
248  * @throws If an error occurs during the listing process.
249  * 
250  * @see Gitteh.GIT_REF_OID
251  * @see Gitteh.GIT_REF_SYMBOLIC
252  * @see Gitteh.GIT_REF_PACKED
253  * @see Gitteh.GIT_REF_LISTALL
254  */
255 Repository.prototype.listReferences = function(flags, callback) {};
256 
257 /**
258  * Orders the Repository to pack all loose {@link Reference}s. This method will
259  * ensure any currently active {@link Reference}s remain valid (even though they
260  * have now been moved inside the packed-references file).  
261  * @param {Function} [callback] If provided, the packing process will be performed asynchronously and the callback notified of the result.
262  * @returns {Boolean} true if successful
263  * @throws If an error occurs during the packing process.
264  */
265 Repository.prototype.packReferences = function(callback) {};
266 
267 /**
268  * Creates a new {@link RevisionWalker}.
269  * @param {Function} [callback] If provided, the walker will be created asychronously.
270  * @returns {RevisionWalker}
271  * @throws If an error occurs.	
272  */
273 Repository.prototype.createWalker = function(callback) {};
274 
275 /**
276  * Loads the Index for the Repository.
277  * @param {Function} [callback] If provided, the Index will be loaded asynchronously, and the result handed to the callback.
278  * @returns {Index}
279  * @throws If an error occurred while loading Index.
280  */
281 Repository.prototype.getIndex = function(callback) {};
282 
283 /**
284  * Creates a new {@link Tag} with the provided data.  
285  * @param {Object} data The data to be stored in the Tag. The fields in this object should be the same as the fields in a {@link Tag}.
286  * @param {Function} [callback] If provided, the tag will be created asynchronously and the newly created Tag provided to the callback.
287  * @return {Tag}
288  * @throws If an error occurred whilst creating the Tag.
289  */
290 Repository.prototype.createTag = function(data, callback) {};
291 
292 /**
293  * Gets a {@link Tag} from the Repository with the given sha1 hash id. 
294  * @param {String} sha1 the sha1 hash ID of the Tag.
295  * @param {Function} [callback] When provided, the Tag will be retrieved asynchronously and results handed to the callback.
296  * @return {Tag}
297  * @throws If an error occurred while loading the Tag.
298  */	
299 Repository.prototype.getTag = function(sha1, callback) {};
300 
301 /**
302  * Creates a new {@link Blob} in the Repository.
303  * @param {Object} data The data for the Blob. Valid fields in this data are the same as the fields in {@link Blob}
304  * @param {Function} [callback] If provided, the Blob will be created asynchronously, and the results passed to the callback.
305  * @returns {Blob}
306  * @throws If an error occurs while creating the Blob.
307  */
308 Repository.prototype.createBlob = function(data, callback) {};
309 
310 /**
311  * Retrieves a Blob from the Repository with given id.
312  * @param {String} sha1 The sha1 hash id of the blob.
313  * @param {Function} [callback] If provided, the Blob will be retrieved asynchronously, and provided to the callback.
314  * @returns {Blob}
315  * @throws If an error occurs while loading the Blob.
316  */
317 Repository.prototype.getBlob = function(sha1, callback) {};
318 
319 /**
320  * Checks if the Repository contains an object with the specified sha1 hash.
321  * @param {String} sha1 SHA1 hash id of the object being searched for.
322  * @param {Function} [callback] If provided, the search will be performed asynchronously, with the result passed back to callback.
323  * @param {Boolean} true if object exists, false if not.
324  * @throws If an error occurs.
325  */
326 Repository.prototype.exists = function(sha1, callback) {};
327 
328 /** 
329  * @class
330  * @property {String} id The id of the commit. This property is read-only.
331  * @property {String} message The commit message.
332  * @property {Signature} author The author of the commit.
333  * @property {Signature} committer The commit committer.
334  * @property {Tree} tree The tree associated with the commit.
335  * @property {Commit[]} parents The parents of this commit, if any.
336  * 
337  * @see Repository#getCommit
338  * @see Repository#createCommit
339  */
340 var Commit = function() {};
341 
342 /**
343  * Saves the commit to the repository. This will update the {@link id} property
344  * when successful.
345  * @param {Function} [callback] If provided, commit will be saved asynchronously, and the result of the save will be passed to the callback.
346  * @return {Boolean} true if successful.
347  * @throws If the commit failed to save.
348  */
349 Commit.prototype.save = function() {}; 
350 
351 /**
352  * A Tree represents the snapshot of a repo for a specific {@link Commit}.
353  * @class
354  * @property {String} id The sha1 hash of this Tree.
355  * @property {TreeEntry[]} entries The entries contained in this Tree.
356  * 
357  * @see Repository#getTree
358  * @see Repository#createTree
359  */
360 var Tree = function() {};
361 
362 /**
363  * Saves the Tree to the Repository. <b>THIS IS UNIMPLEMENTED CURRENTLY</b>
364  * @throws If called, because it's currently unimplemented.
365  */
366 Tree.prototype.save = function() {};
367 
368 /**
369  * A single entry in a {@link Tree}. Note this isn't a "real" class, as there's
370  * no constructor. Tree entries are just plain old Javascript objects. This is  
371  * just here for reference.
372  * @class
373  * @property {String} id SHA1 hash of the {@link Blob} this entry points to.
374  * @property {String} name Filename of the entry.
375  * @property {Integer} attributes File attributes for the entry.
376  */
377 var TreeEntry = function() {};
378 
379 /**
380  * A reference serves as a pointer of sorts to a specific Commit. References can
381  * either be <i>direct</i> or <i>symbolic</i>. Direct references point to a commit
382  * OID, symbolic references point to other references (which may also be symbolic).
383  * @class
384  * @property {String} name The name of the reference - e.g refs/heads/master
385  * @property {String} type The type of reference this is. Can be either "oid" or "symbolic". CANNOT be changed.
386  * @property {String} target Either the SHA1 hash of the {@link Commit} being pointed to by this Reference, if it's type is "oid". If it's a symbolic Reference, this will point to another reference name.
387  * 
388  * @see Repository#getReference
389  * @see Repository#createOidReference
390  * @see Repository#createSymbolicReference
391  */ 
392 var Reference = function() {};
393 
394 /**
395  * Renames this Reference. Name of the new Reference must not already exist in the Repository.
396  * @param {String} newName The new name.
397  * @param {Function} [callback] If provided, the rename will occur asynchronously, and the callback will be fired when rename has completed.
398  * @return {Boolean} true if successful.
399  * @throws If an error occurred during renaming process.
400  */
401 Reference.prototype.rename = function(newName, callback) { };
402 
403 /**
404  * Deletes the Reference permanently. Once deleted, the Reference will no longer
405  * be accessible from the Repository. It will be deleted from the filesystem
406  * also. If this Reference is involved in any symbolic link chains, they will
407  * become invalid. After calling this, any further calls on the Reference will
408  * throw an Error.
409  * @name Reference#delete
410  * @function
411  * @param {Function} [callback] If provided, the deletion will occur asynchronously and return the status of the delete to the callback.
412  * @return {Boolean} true if successful
413  * @throws If an error occurred while deleting the Reference.
414  */
415 // Used @name tag because Eclipse linter doesn't like method name being "delete".
416 //Reference.prototype.delete = function(callback) { };
417 
418 /**
419  * Resolves this Reference to a direct oid Reference. This means it will follow
420  * symbolic links until it arrives at the direct link pointing to a {@ link Commit}.
421  * Note that if you call this on a Reference that is already pointing to a Commit, it
422  * will just return the Reference.
423  * @param {Function} [callback] When given, the resolution will be done asynchronously and the resulting Reference passed to the callback.
424  * @return {Reference} The result of the resolution.
425  * @throws If an error occurred while resolving the Reference.
426  */
427 Reference.prototype.resolve = function(callback) { };
428 
429 /**
430  * Sets the target of this Reference. This change is immediate. <b>Note:</b> You
431  * can't change the type of a Reference. For example, if this Reference is an
432  * OID reference, you can't set the target to another Reference. If you need to
433  * do this, delete the original ref, and recreate it as the other type. 
434  * @param {String} newTarget either the oid, or name of another Reference. 
435  * @param {Function} [callback] If provided, the Reference will be re-targeted asynchronously. The callback will be notified when this occurs.
436  * @return {Boolean} true if successful.
437  * @throws If an error occurred while setting target.
438  */
439 Reference.prototype.setTarget = function(newTarget, callback) { };
440 
441 /**
442  * List OID (direct) References
443  * @static
444  */
445 Gitteh.GIT_REF_OID = undefined;
446 /**
447  * List symbolic (indirect) References.
448  * @static
449  */
450 Gitteh.GIT_REF_SYMBOLIC = undefined;
451 /**
452  * Include packed References in list.
453  * @static
454  */
455 Gitteh.GIT_REF_PACKED = undefined;
456 /**
457  * List all References in the Repository.
458  * @static
459  */
460 Gitteh.GIT_REF_LISTALL = undefined;
461 
462 /**
463  * A Blob is a binary store of a specific file that has been committed into a
464  * Repository at some point.
465  * @class
466  * @property {String} id The SHA1 id of the Blob.
467  * @property {Buffer} data The data this Blob contains.
468  * 
469  * @see Repository#createBlob
470  * @see Repository#getBlob
471  */
472 var Blob = function() {};
473 
474 /**
475  * Saves this blob to Repository and updates its id.
476  * @param {Function} [callback] If provided, the save will be performed asynchronously, and the result passed to the callback.
477  * @return {Boolean} true if successful.
478  * @throws If save was not successful.
479  */
480 Blob.prototype.save = function(callback) {};
481 
482 /**
483  * The Index represents the cache Git stores for your working directory. When
484  * you "stage" a file in Git, this is basically just a command that will add 
485  * or update your file in the Git index. Running a Commit in Git is essentially
486  * just writing a Commit with a Tree that matches an Index. <b>Note:</b> There
487  * will be a method soon to create a Tree from an opened Index, this feature has
488  * not yet been implemented by libgit2, as soon as it is it will be in Gitteh.
489  * @class
490  * @property {Integer} entryCount <i>Read-only</i> How many entries are contained in the Index.
491  * 
492  * @see Repository#getIndex
493  */
494 var Index = function() {};
495 
496 /**
497  * Retrieves an {@link IndexEntry} from the Index.
498  * @param {Integer} index The index to retrieve. 
499  * @param {Function} [callback] When provided, IndexEntry will be retrieved asynchronously and provided back to the callback.
500  * @return {IndexEntry}
501  * @throws If index is out of bounds, or some other error occurs.
502  */
503 Index.prototype.getEntry = function(index, callback) {};
504 
505 /**
506  * Searches the Index for an entry that matches the given filename.
507  * @param {String} [fileName] The filename of entry to search for.
508  * @param {Function} [callback] If provided, entry will be searched for in a non-blocking manner, and results returned to the callback.
509  * @return {IndexEntry}
510  * @throws If entry could not be found, or some other error occurs.
511  */
512 Index.prototype.findEntry = function(fileName, callback) {};
513 
514 /**
515  * Adds an entry to the Index for the given fileName. This file should already 
516  * exist in the working directory of the Repository. <b>Note:</b> this function
517  * will fail if called on a Index for a bare repository, as it has no working
518  * directory.
519  * @param {String} fileName Name of the file to update index entry for.
520  * @param {Function} [callback] When provided, the callback will be notified when the entry has been added asynchronously.
521  * @returns {Boolean} true if successful
522  * @throws If there was an error adding the entry.
523  */
524 Index.prototype.addEntry = function(fileName, callback) {};
525 
526 /**
527  * Changes to an Index will not be updated on the actual index file until this 
528  * method is called.
529  * @param {Function} [callback] When provided, the writeback will be performed in an asynchronous fashion, and the result will be passed back to the callback.
530  * @returns {Boolean} true if successful.
531  * @throws If there was an error writing the Index.
532  */
533 Index.prototype.write = function(callback) {};
534 
535 /**
536  * Represents a single entry in the Git {@link Index}. <b>Note:</b> While the 
537  * constructor for this class <i>is</i> being exposed, it is not recommended to
538  * extend its functionality, as it may be removed altogether in a future release.
539  * @class
540  * @property {Date} ctime
541  * @property {Date} mtime
542  * @property {Integer} dev
543  * @property {Integer} ino
544  * @property {Integer} mode
545  * @property {Integer} uid
546  * @property {Integer} gid
547  * @property {Integer} file_size
548  * @property {String} oid
549  * @property {Integer} flags
550  * @property {Integer} flags_extended
551  * @property {String} path
552  */
553 var IndexEntry = function() {};
554 
555 /**
556  * A RevisionWalker provides a clean interface to walk the commit history of a
557  * {@link Repository}. A RevisionWalker may be obtained via {@link Repository#createWalker}
558  * @class 
559  * 
560  * @see Repository#createWalker
561  */
562 var RevisionWalker = function() {};
563 
564 /**
565  * Pushes a Commit onto the Revision Walker to begin the walking process.
566  * @param {String|Commit} commit The commit to push onto the walker. Can either be an sha1 id string, or a previously loaded Commit.
567  * @returns {Boolean} true if successful.
568  * @throws If there was an error pushing the Commit.
569  */
570 RevisionWalker.prototype.push = function(commit, callback) {};
571 
572 /**
573  * Hides a specific Commit (and all its ancestors/descendants) from the walker.
574  * @param {String|Commit} commit The commit to ignore. Can either be a sha1 id string, or a previously loaded Commit.
575  * @param {Function} [callback] If provided, the hide process will be performed in a non-blocking fashion, and the results passed back to the callback.
576  * @returns {Boolean} true if successful.
577  * @throws If there was an error hiding the Commit.
578  */
579 RevisionWalker.prototype.hide = function(commit, callback) {};
580 
581 /**
582  * Gets the next Commit in the queue from the RevisionWalker.
583  * @param {Function} [callback] If provided, the next Commit will be retrieved asynchronously, and the results passed back to callback.
584  * @returns {Commit}
585  * @throws If an error occurs while getting the next Commit.
586  */
587 RevisionWalker.prototype.next = function(callback) {};
588 
589 /**
590  * Sets a specific sorting method on the RevisionWalker.
591  * @param {Integer} sorting The sorting method to use on this walker. The valid values are {@link Gitteh.GIT_SORT_NONE}, {@link Gitteh.GIT_SORT_TOPOLOGICAL}, {@link Gitteh.GIT_SORT_TIME}, and {@link Gitteh.GIT_SORT_REVERSE}.
592  * @param {Function} [callback] If provided, walker will be configured with sorting options in a non-blocking manner, and the results of the operation passsed to the callback.
593  * @returns {Boolean} true if successful.
594  * @throws If an error occurred while setting sorting.
595  * @see Gitteh.GIT_SORT_NONE
596  * @see Gitteh.GIT_SORT_TOPOLOGICAL
597  * @see Gitteh.GIT_SORT_TIME
598  * @see Gitteh.GIT_SORT_REVERSE
599  */
600 RevisionWalker.prototype.sort = function(sorting, callback) {};
601 
602 /**
603  * Resets the RevisionWalker to an identity state ready to begin another walk.
604  * @param {Function} [callback] If provided, the walker will be reset asynchronously and the results passed to the callback.
605  * @returns {Boolean} true if successful.
606  * @throws If an error occurred.
607  */
608 RevisionWalker.prototype.reset = function(callback) {};
609 
610 /**
611  * @public
612  * @static
613  */
614 Gitteh.GIT_SORT_NONE = undefined;
615 /**
616  * @public
617  * @static
618  */
619 Gitteh.GIT_SORT_TOPOLOGICAL = undefined;
620 /**
621  * @public
622  * @static
623  */
624 Gitteh.GIT_SORT_TIME = undefined;
625 /**
626  * @public
627  * @static
628  */
629 Gitteh.GIT_SORT_REVERSE = undefined;
630 
631 /**
632  * @class
633  * @property {String} id <i>Read-only</i> The sha1 hash of this Tag.
634  * @property {String} message The message associated with this Tag.
635  * @property {String} name The name of this Tag.
636  * @property {Signature} tagger The person who created this Tag.
637  * @property {String} targetId The object this Tag is pointing at.
638  * @property {String} targetType The type of object this Tag is pointing at.
639  * 
640  * @see Repository#getTag
641  * @see Repository#createTag
642  */
643 var Tag = function() {};
644 
645 /**
646  * Saves the data contained in this Tag and updates the ID.
647  * @param {Function} [callback] If provided, the Tag will be saved asynchronously and the results provided to the callback.
648  * @returns {Boolean} true if successful.
649  * @throws If an error occurs during save process.
650  */
651 Tag.prototype.save = function(callback) {};
652 
653 /**
654  * A Signature is used to store metadata about a person. It is used in {@link Commit}s
655  * and {@link Tag}s. Note that there is no actual constructor for a Signature,
656  * it's just a regular JS object. This documentation just serves as a guide to
657  * what properties should be in a Signature. 
658  * @class
659  * @property {String} name 
660  * @property {String} email
661  * @property {Date} time
662  * @property {Integer} timeOffset In seconds. e.g GMT+10 is stored as 600.
663  */
664 var Signature = function() {};
665 
666 /**
667  * Errors thrown by Gitteh will generally include additional data if it's a Git
668  * related issue. Note that there is no actual Error type called GitError, this 
669  * is just for illustrative purposes only.
670  * @class
671  * @property {Integer} gitError The error number. The possible errors are detailed in {@link Gitteh.error}.
672  * @property {String} gitErrorStr A short message explaining the error.
673  */
674 var GitError = function() {};