git2 0.1.9

Bindings to libgit2 for interoperating with git repositories. This library is both threadsafe and memory safe and allows both reading and writing git repositories.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
//! # libgit2 bindings for Rust
//!
//! This library contains bindings to the [libgit2][1] C library which is used
//! to manage git repositories. The library itself is a work in progress and is
//! likely lacking some bindings here and there, so be warned.
//!
//! [1]: https://libgit2.github.com/
//!
//! The git2-rs library strives to be as close to libgit2 as possible, but also
//! strives to make using libgit2 as safe as possible. All resource management
//! is automatic as well as adding strong types to all interfaces (including
//! `Result`)
//!
//! ## Creating a `Repository`
//!
//! The `Repository` is the source from which almost all other objects in git-rs
//! are spawned. A repository can be created through opening, initializing, or
//! cloning.
//!
//! ### Initializing a new repository
//!
//! The `init` method will create a new repository, assuming one does not
//! already exist.
//!
//! ```no_run
//! use git2::Repository;
//!
//! let path = Path::new("/path/to/a/repo");
//! let repo = match Repository::init(&path) {
//!     Ok(repo) => repo,
//!     Err(e) => panic!("failed to init `{}`: {}", path.display(), e),
//! };
//! ```
//!
//! ### Opening an existing repository
//!
//! ```no_run
//! use git2::Repository;
//!
//! let path = Path::new("/path/to/a/repo");
//! let repo = match Repository::open(&path) {
//!     Ok(repo) => repo,
//!     Err(e) => panic!("failed to open `{}`: {}", path.display(), e),
//! };
//! ```
//!
//! ### Cloning an existing repository
//!
//! ```no_run
//! use git2::Repository;
//!
//! let url = "https://github.com/alexcrichton/git2-rs";
//! let path = Path::new("/path/to/a/repo");
//! let repo = match Repository::clone(url, &path) {
//!     Ok(repo) => repo,
//!     Err(e) => panic!("failed to clone `{}`: {}", path.display(), e),
//! };
//! ```
//!
//! ## Working with a `Repository`
//!
//! All deriviative objects, references, etc are attached to the lifetime of the
//! source `Repository`, to ensure that they do not outlive the repository
//! itself.

#![feature(unsafe_destructor)]
#![deny(missing_docs)]
#![cfg_attr(test, deny(warnings))]

extern crate libc;
extern crate url;
extern crate "libgit2-sys" as raw;

use std::ffi::{self, CString};
use std::fmt;
use std::mem;
use std::str;
use std::sync::{Once, ONCE_INIT};

pub use blob::Blob;
pub use branch::{Branch, Branches};
pub use buf::Buf;
pub use commit::{Commit, Parents};
pub use config::{Config, ConfigEntry, ConfigEntries};
pub use cred::{Cred, CredentialHelper};
pub use diff::{Diff, DiffDelta, DiffFile, DiffOptions, Deltas};
pub use diff::{DiffLine, DiffHunk, DiffStats};
pub use error::Error;
pub use index::{Index, IndexEntry, IndexEntries, IndexMatchedPath};
pub use note::{Note, Notes};
pub use object::Object;
pub use oid::Oid;
pub use pathspec::{Pathspec, PathspecMatchList, PathspecFailedEntries};
pub use pathspec::{PathspecDiffEntries, PathspecEntries};
pub use push::{Push, PushStatus};
pub use reference::{Reference, References, ReferenceNames};
pub use refspec::Refspec;
pub use remote::{Remote, Refspecs, RemoteHead};
pub use remote_callbacks::{RemoteCallbacks, Credentials, TransferProgress};
pub use remote_callbacks::{TransportMessage, Progress, UpdateTips};
pub use repo::{Repository, RepositoryInitOptions};
pub use revspec::Revspec;
pub use revwalk::Revwalk;
pub use signature::Signature;
pub use status::{StatusOptions, Statuses, StatusIter, StatusEntry, StatusShow};
pub use string_array::{StringArray, StringArrayItems, StringArrayBytes};
pub use submodule::Submodule;
pub use tag::Tag;
pub use time::{Time, IndexTime};
pub use tree::{Tree, TreeEntry};

/// An enumeration of possible errors that can happen when working with a git
/// repository.
#[derive(PartialEq, Eq, Clone, Show, Copy)]
pub enum ErrorCode {
    /// Generic error
    GenericError,
    /// Requested object could not be found
    NotFound,
    /// Object exists preventing operation
    Exists,
    /// More than one object matches
    Ambiguous,
    /// Output buffer too short to hold data
    BufSize,
    /// Operation not allowed on bare repository
    User,
    /// Operation not allowed on bare repository
    BareRepo,
    /// HEAD refers to branch with no commits
    UnbornBranch,
    /// Merge in progress prevented operation
    Unmerged,
    /// Reference was not fast-forwardable
    NotFastForward,
    /// Name/ref spec was not in a valid format
    InvalidSpec,
    /// Merge conflicts prevented operation
    MergeConflict,
    /// Lock file prevented operation
    Locked,
    /// Reference value does not match expected
    Modified,
}

/// A listing of the possible states that a repository can be in.
#[derive(PartialEq, Eq, Clone, Show, Copy)]
#[allow(missing_docs)]
pub enum RepositoryState {
    Clean,
    Merge,
    Revert,
    CherryPick,
    Bisect,
    Rebase,
    RebaseInteractive,
    RebaseMerge,
    ApplyMailbox,
    ApplyMailboxOrRebase,
}

/// An enumeration of the possible directions for a remote.
#[derive(Copy)]
pub enum Direction {
    /// Data will be fetched (read) from this remote.
    Fetch,
    /// Data will be pushed (written) to this remote.
    Push,
}

/// An enumeration of the operations that can be performed for the `reset`
/// method on a `Repository`.
#[derive(Copy)]
pub enum ResetType {
    /// Move the head to the given commit.
    Soft,
    /// Soft plus reset the index to the commit.
    Mixed,
    /// Mixed plus changes in the working tree are discarded.
    Hard,
}

/// An enumeration all possible kinds objects may have.
#[derive(PartialEq, Eq, Copy)]
pub enum ObjectType {
    /// An object which corresponds to a any git object
    Any,
    /// An object which corresponds to a git commit
    Commit,
    /// An object which corresponds to a git tree
    Tree,
    /// An object which corresponds to a git blob
    Blob,
    /// An object which corresponds to a git tag
    Tag,
}

/// An enumeration for the possible types of branches
#[derive(PartialEq, Eq, Show, Copy)]
pub enum BranchType {
    /// A local branch not on a remote.
    Local,
    /// A branch for a remote.
    Remote,
}

/// An enumeration of the possible priority levels of a config file.
///
/// The levels corresponding to the escalation logic (higher to lower) when
/// searching for config entries.
#[derive(PartialEq, Eq, Show, Copy)]
pub enum ConfigLevel {
    /// System-wide configuration file, e.g. /etc/gitconfig
    System,
    /// XDG-compatible configuration file, e.g. ~/.config/git/config
    XDG,
    /// User-specific configuration, e.g. ~/.gitconfig
    Global,
    /// Reopsitory specific config, e.g. $PWD/.git/config
    Local,
    /// Application specific configuration file
    App,
    /// Highest level available
    Highest,
}

bitflags! {
    #[doc = "
Orderings that may be specified for Revwalk iteration.
"]
    flags Sort: uint {
        const SORT_NONE = raw::GIT_SORT_NONE as uint,
        const SORT_TOPOLOGICAL = raw::GIT_SORT_TOPOLOGICAL as uint,
        const SORT_TIME = raw::GIT_SORT_TIME as uint,
        const SORT_REVERSE = raw::GIT_SORT_REVERSE as uint,
    }
}

bitflags! {
    #[doc = "
Types of credentials that can be requested by a credential callback.
"]
    flags CredentialType: uint {
        const USER_PASS_PLAINTEXT = raw::GIT_CREDTYPE_USERPASS_PLAINTEXT as uint,
        const SSH_KEY = raw::GIT_CREDTYPE_SSH_KEY as uint,
        const SSH_CUSTOM = raw::GIT_CREDTYPE_SSH_CUSTOM as uint,
        const DEFAULT = raw::GIT_CREDTYPE_DEFAULT as uint,
        const SSH_INTERACTIVE = raw::GIT_CREDTYPE_SSH_INTERACTIVE as uint,
    }
}

bitflags! {
    #[doc = "
Flags for APIs that add files matching pathspec
"]
    flags IndexAddOption: u32 {
        const ADD_DEFAULT = raw::GIT_INDEX_ADD_DEFAULT as u32,
        const ADD_FORCE = raw::GIT_INDEX_ADD_FORCE as u32,
        const ADD_DISABLE_PATHSPEC_MATCH =
                raw::GIT_INDEX_ADD_DISABLE_PATHSPEC_MATCH as u32,
        const ADD_CHECK_PATHSPEC = raw::GIT_INDEX_ADD_CHECK_PATHSPEC as u32,
    }
}

bitflags! {
    #[doc = "
Flags for the return value of `Repository::revparse`
"]
    flags RevparseMode: u32 {
        const REVPARSE_SINGLE = raw::GIT_REVPARSE_SINGLE as u32,
        const REVPARSE_RANGE = raw::GIT_REVPARSE_RANGE as u32,
        const REVPARSE_MERGE_BASE = raw::GIT_REVPARSE_MERGE_BASE as u32,
    }
}

#[macro_use]
mod call;
mod panic;
mod util;

pub mod build;

mod blob;
mod branch;
mod buf;
mod commit;
mod config;
mod cred;
mod diff;
mod error;
mod index;
mod note;
mod object;
mod oid;
mod pathspec;
mod push;
mod reference;
mod refspec;
mod remote;
mod remote_callbacks;
mod repo;
mod revspec;
mod revwalk;
mod signature;
mod status;
mod string_array;
mod submodule;
mod tag;
mod time;
mod tree;

#[cfg(test)] mod test;

fn init() {
    static INIT: Once = ONCE_INIT;
    INIT.call_once(|| unsafe {
        raw::openssl_init();
        let r = raw::git_libgit2_init();
        assert!(r >= 0,
                "couldn't initialize the libgit2 library: {}", r);
        assert_eq!(libc::atexit(shutdown), 0);
    });
    extern fn shutdown() { unsafe { raw::git_libgit2_shutdown() } }
}

unsafe fn opt_bytes<'a, T>(_: &'a T,
                           c: *const libc::c_char) -> Option<&'a [u8]> {
    if c.is_null() {
        None
    } else {
        Some(mem::transmute(ffi::c_str_to_bytes(&c)))
    }
}

impl ObjectType {
    /// Convert an object type to its string representation.
    pub fn str(&self) -> &'static str {
        unsafe {
            let ptr = call!(raw::git_object_type2string(*self));
            let bytes = ffi::c_str_to_bytes(&ptr);
            let s = str::from_utf8(bytes).unwrap();
            mem::transmute::<&str, &'static str>(s)
        }
    }

    /// Determine if the given git_otype is a valid loose object type.
    pub fn is_loose(&self) -> bool {
        unsafe { (call!(raw::git_object_typeisloose(*self)) == 1) }
    }

    /// Convert a raw git_otype to an ObjectType
    pub fn from_raw(raw: raw::git_otype) -> Option<ObjectType> {
        match raw {
            raw::GIT_OBJ_ANY => Some(ObjectType::Any),
            raw::GIT_OBJ_BAD => None,
            raw::GIT_OBJ__EXT1 => None,
            raw::GIT_OBJ_COMMIT => Some(ObjectType::Commit),
            raw::GIT_OBJ_TREE => Some(ObjectType::Tree),
            raw::GIT_OBJ_BLOB => Some(ObjectType::Blob),
            raw::GIT_OBJ_TAG => Some(ObjectType::Tag),
            raw::GIT_OBJ__EXT2 => None,
            raw::GIT_OBJ_OFS_DELTA => None,
            raw::GIT_OBJ_REF_DELTA => None,
        }
    }

    /// Convert this kind into its raw representation
    pub fn raw(&self) -> raw::git_otype {
        call::convert(self)
    }

    /// Convert a string object type representation to its object type.
    pub fn from_str(s: &str) -> Option<ObjectType> {
        let s = CString::from_slice(s.as_bytes());
        let raw = unsafe { call!(raw::git_object_string2type(s)) };
        ObjectType::from_raw(raw)
    }
}

impl fmt::Show for ObjectType {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        self.str().fmt(f)
    }
}

impl ConfigLevel {
    /// Converts a raw configuration level to a ConfigLevel
    pub fn from_raw(raw: raw::git_config_level_t) -> ConfigLevel {
        match raw {
            raw::GIT_CONFIG_LEVEL_SYSTEM => ConfigLevel::System,
            raw::GIT_CONFIG_LEVEL_XDG => ConfigLevel::XDG,
            raw::GIT_CONFIG_LEVEL_GLOBAL => ConfigLevel::Global,
            raw::GIT_CONFIG_LEVEL_LOCAL => ConfigLevel::Local,
            raw::GIT_CONFIG_LEVEL_APP => ConfigLevel::App,
            raw::GIT_CONFIG_HIGHEST_LEVEL => ConfigLevel::Highest,
        }
    }
}

bitflags! {
    #[doc = "
Flags for repository status
"]
    flags Status: u32 {
        const STATUS_CURRENT = raw::GIT_STATUS_CURRENT as u32,

        const STATUS_INDEX_NEW = raw::GIT_STATUS_INDEX_NEW as u32,
        const STATUS_INDEX_MODIFIED = raw::GIT_STATUS_INDEX_MODIFIED as u32,
        const STATUS_INDEX_DELETED = raw::GIT_STATUS_INDEX_DELETED as u32,
        const STATUS_INDEX_RENAMED = raw::GIT_STATUS_INDEX_RENAMED as u32,
        const STATUS_INDEX_TYPECHANGE = raw::GIT_STATUS_INDEX_TYPECHANGE as u32,

        const STATUS_WT_NEW = raw::GIT_STATUS_WT_NEW as u32,
        const STATUS_WT_MODIFIED = raw::GIT_STATUS_WT_MODIFIED as u32,
        const STATUS_WT_DELETED = raw::GIT_STATUS_WT_DELETED as u32,
        const STATUS_WT_TYPECHANGE = raw::GIT_STATUS_WT_TYPECHANGE as u32,
        const STATUS_WT_RENAMED = raw::GIT_STATUS_WT_RENAMED as u32,

        const STATUS_IGNORED = raw::GIT_STATUS_IGNORED as u32,
    }
}

bitflags! {
    #[doc = "
Mode options for RepositoryInitOptions
"]
    flags RepositoryInitMode: u32 {
        #[doc = "Use permissions configured by umask - the default"]
        const REPOSITORY_INIT_SHARED_UMASK =
                    raw::GIT_REPOSITORY_INIT_SHARED_UMASK as u32,
        #[doc = "Use `--shared=group` behavior, chmod'ing the new repo to be \
                 group writable and \"g+sx\" for sticky group assignment"]
        const REPOSITORY_INIT_SHARED_GROUP =
                    raw::GIT_REPOSITORY_INIT_SHARED_GROUP as u32,
        #[doc = "Use `--shared=all` behavior, adding world readability."]
        const REPOSITORY_INIT_SHARED_ALL =
                    raw::GIT_REPOSITORY_INIT_SHARED_ALL as u32,
    }
}

/// What type of change is described by a `DiffDelta`?
#[derive(Copy)]
pub enum Delta {
    /// No changes
    Unmodified,
    /// Entry does not exist in old version
    Added,
    /// Entry does not exist in new version
    Deleted,
    /// Entry content changed between old and new
    Modified,
    /// Entry was renamed wbetween old and new
    Renamed,
    /// Entry was copied from another old entry
    Copied,
    /// Entry is ignored item in workdir
    Ignored,
    /// Entry is untracked item in workdir
    Untracked,
    /// Type of entry changed between old and new
    Typechange,
    /// Entry is unreadable
    Unreadable,
}

bitflags! {
    #[doc = r#"
Return codes for submodule status.

A combination of these flags will be returned to describe the status of a
submodule.  Depending on the "ignore" property of the submodule, some of
the flags may never be returned because they indicate changes that are
supposed to be ignored.

Submodule info is contained in 4 places: the HEAD tree, the index, config
files (both .git/config and .gitmodules), and the working directory.  Any
or all of those places might be missing information about the submodule
depending on what state the repo is in.  We consider all four places to
build the combination of status flags.

There are four values that are not really status, but give basic info
about what sources of submodule data are available.  These will be
returned even if ignore is set to "ALL".

* IN_HEAD   - superproject head contains submodule
* IN_INDEX  - superproject index contains submodule
* IN_CONFIG - superproject gitmodules has submodule
* IN_WD     - superproject workdir has submodule

The following values will be returned so long as ignore is not "ALL".

* INDEX_ADDED       - in index, not in head
* INDEX_DELETED     - in head, not in index
* INDEX_MODIFIED    - index and head don't match
* WD_UNINITIALIZED  - workdir contains empty directory
* WD_ADDED          - in workdir, not index
* WD_DELETED        - in index, not workdir
* WD_MODIFIED       - index and workdir head don't match

The following can only be returned if ignore is "NONE" or "UNTRACKED".

* WD_INDEX_MODIFIED - submodule workdir index is dirty
* WD_WD_MODIFIED    - submodule workdir has modified files

Lastly, the following will only be returned for ignore "NONE".

* WD_UNTRACKED      - wd contains untracked files
"#]
    flags SubmoduleStatus: u32 {
        const SUBMODULE_STATUS_IN_HEAD =
                raw::GIT_SUBMODULE_STATUS_IN_HEAD as u32,
        const SUBMODULE_STATUS_IN_INDEX =
                raw::GIT_SUBMODULE_STATUS_IN_INDEX as u32,
        const SUBMODULE_STATUS_IN_CONFIG =
                raw::GIT_SUBMODULE_STATUS_IN_CONFIG as u32,
        const SUBMODULE_STATUS_IN_WD =
                raw::GIT_SUBMODULE_STATUS_IN_WD as u32,
        const SUBMODULE_STATUS_INDEX_ADDED =
                raw::GIT_SUBMODULE_STATUS_INDEX_ADDED as u32,
        const SUBMODULE_STATUS_INDEX_DELETED =
                raw::GIT_SUBMODULE_STATUS_INDEX_DELETED as u32,
        const SUBMODULE_STATUS_INDEX_MODIFIED =
                raw::GIT_SUBMODULE_STATUS_INDEX_MODIFIED as u32,
        const SUBMODULE_STATUS_WD_UNINITIALIZED =
                raw::GIT_SUBMODULE_STATUS_WD_UNINITIALIZED as u32,
        const SUBMODULE_STATUS_WD_ADDED =
                raw::GIT_SUBMODULE_STATUS_WD_ADDED as u32,
        const SUBMODULE_STATUS_WD_DELETED =
                raw::GIT_SUBMODULE_STATUS_WD_DELETED as u32,
        const SUBMODULE_STATUS_WD_MODIFIED =
                raw::GIT_SUBMODULE_STATUS_WD_MODIFIED as u32,
        const SUBMODULE_STATUS_WD_INDEX_MODIFIED =
                raw::GIT_SUBMODULE_STATUS_WD_INDEX_MODIFIED as u32,
        const SUBMODULE_STATUS_WD_WD_MODIFIED =
                raw::GIT_SUBMODULE_STATUS_WD_WD_MODIFIED as u32,
        const SUBMODULE_STATUS_WD_UNTRACKED =
                raw::GIT_SUBMODULE_STATUS_WD_UNTRACKED as u32,
    }

}

bitflags! {
    #[doc = r#"
"#]
    flags PathspecFlags: u32 {
        const PATHSPEC_DEFAULT = raw::GIT_PATHSPEC_DEFAULT as u32,
        const PATHSPEC_IGNORE_CASE = raw::GIT_PATHSPEC_IGNORE_CASE as u32,
        const PATHSPEC_USE_CASE = raw::GIT_PATHSPEC_USE_CASE as u32,
        const PATHSPEC_NO_GLOB = raw::GIT_PATHSPEC_NO_GLOB as u32,
        const PATHSPEC_NO_MATCH_ERROR = raw::GIT_PATHSPEC_NO_MATCH_ERROR as u32,
        const PATHSPEC_FIND_FAILURES = raw::GIT_PATHSPEC_FIND_FAILURES as u32,
        const PATHSPEC_FAILURES_ONLY = raw::GIT_PATHSPEC_FAILURES_ONLY as u32,
    }
}

/// Possible output formats for diff data
#[derive(Copy)]
pub enum DiffFormat {
    /// full git diff
    Patch,
    /// just the headers of the patch
    PatchHeader,
    /// like git diff --raw
    Raw,
    /// like git diff --name-only
    NameOnly,
    /// like git diff --name-status
    NameStatus,
}

#[cfg(test)]
mod tests {
    use super::ObjectType;

    #[test]
    fn convert() {
        assert_eq!(ObjectType::Blob.str(), "blob");
        assert_eq!(ObjectType::from_str("blob"), Some(ObjectType::Blob));
        assert!(ObjectType::Blob.is_loose());
    }

}