gix_archive/lib.rs
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
//! The implementation of creating an archive from a worktree stream, similar to `git archive`.
//!
//! ## Deviation
//!
//! This implementation is early and just does the basics. Git does more to support more context when filtering and to keep
//! more information about entries in the various archive formats.
//! `tar` is implemented in a very basic fashion only.
//!
//! ## Feature Flags
//! All features are related to which container formats are available.
#![cfg_attr(
all(doc, feature = "document-features"),
doc = ::document_features::document_features!()
)]
#![cfg_attr(all(doc, feature = "document-features"), feature(doc_cfg, doc_auto_cfg))]
#![deny(rust_2018_idioms, missing_docs)]
#![forbid(unsafe_code)]
use bstr::BString;
/// The error returned by [`write_stream()`].
#[derive(Debug, thiserror::Error)]
#[allow(missing_docs)]
pub enum Error {
#[error(transparent)]
Io(#[from] std::io::Error),
#[error(transparent)]
NextStreamEntry(#[from] gix_worktree_stream::entry::Error),
#[error("The internal format cannot be used as an archive, it's merely a debugging tool")]
InternalFormatMustNotPersist,
#[error("Support for the format '{wanted:?}' was not compiled in")]
SupportNotCompiledIn { wanted: Format },
#[error("Cannot create a zip archive if output stream does not support seek")]
ZipWithoutSeek,
#[error("Cannot use modification as it is not within the supported bounds")]
InvalidModificationTime(#[source] Box<dyn std::error::Error + Send + Sync + 'static>),
}
/// The supported container formats for use in [`write_stream()`].
#[derive(Default, PartialEq, Eq, Copy, Clone, Debug)]
pub enum Format {
/// An internal format that is suitable only for intra-process communication.
///
/// All transformations in the options are ignored. Calling [`write_stream`] is disallowed
/// as it's more efficient to call [gix_worktree_stream::Stream::into_read()] right away.
/// It is provided here as a basis available without extra dependencies, and as a debugging tool.
#[default]
InternalTransientNonPersistable,
/// A standard `tar` archive.
///
/// Use it as well if a custom container format is desired. The idea is to decode it on a separate thread
/// to rewrite the data to the desired format.
Tar,
/// A convenience format that will `gzip` deflate the `tar` stream.
TarGz {
/// If `None`, use the default compression level. Otherwise use the given one which
/// ranges from 0-9 for the deflate algorithm.
compression_level: Option<u8>,
},
/// A standard `zip` archive. Note that this format silently converts illformed UTF-8 to UTF-8, which will
/// equal a change of path.
///
/// Requires the `zip` feature toggle to have an effect.
///
/// ### Shortcoming
///
/// Even though symlinks are stored as such, for some reason at least on MacOS those aren't restored. That works,
/// however, when letting `git` create the archive.
Zip {
/// If `None`, use the default compression level. Otherwise use the given one which
/// ranges from 0-9 for the deflate algorithm.
compression_level: Option<u8>,
},
}
/// Options for configuring [`write_stream()`].
#[derive(Clone, Debug)]
pub struct Options {
/// The archive's format.
pub format: Format,
/// Given a `path`, originating in the git tree, to place into the archive, put `<prefix>/path` in front of it.
///
/// Note that that `/` should be used as separator, and that a prefix directory has to end with `/`.
pub tree_prefix: Option<BString>,
/// The modification time for all entries in the archive as seen since UNIX epoch.
///
/// Defaults to the current time. The caller may set this to the commit time if available.
pub modification_time: gix_date::SecondsSinceUnixEpoch,
}
impl Default for Options {
fn default() -> Self {
Options {
format: Default::default(),
tree_prefix: None,
modification_time: std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|t| t.as_secs() as i64)
.unwrap_or_default(),
}
}
}
mod write;
pub use write::{write_stream, write_stream_seek};