API Design - Allow for immutable and mutable references.

[colbyn]

I'm trying to figure out how to add new remotes to a git repo.

Anyway regarding,

/// A remote which represents a way to interact with hosts for remote clones of the parent repository.
#[derive(Debug, Clone, PartialEq)]
pub struct Remote<'repo> {/*…*/}

Thereafter I'm completely prevented from doing any mutable operations on a Repository. What if, instead of using a lifetime, we just used a generic in place of a specific repository type, like so:

/// A remote which represents a way to interact with hosts for remote clones of the parent repository.
#[derive(Debug, Clone, PartialEq)]
pub struct Remote<T> {
    /*…*/
    pub(crate) repo: T,
}

So we can have methods that return mutable and immutable references

pub fn remote_at<Url, E>(&self, url: Url) -> Result<Remote<&'_ Repository >, remote::init::Error>
pub fn remote_at_mut<Url, E>(&mut self, url: Url) -> Result<Remote<&'_ mut Repository >, remote::init::Error>

Although I haven't demoed/tested this idea so perhaps there are nuances I haven't considered...

Personally I'd rather have a types that don't require references to their parent, it just complicates things to no end, if methods need access to such I'd rather pass it in as an argument....

[colbyn]

So over at this fork I rewrote a few things

/// A remote which represents a way to interact with hosts for remote clones of the parent repository.
#[derive(Debug, Clone, PartialEq)]
pub struct Remote<T> {
    /*…*/
    pub(crate) repo: T,
}

/// A remote with a reference to a given repository. 
pub type RemoteRef<'a> = Remote<&'a Repository>;

/// A remote with a mutable reference to a given repository. 
pub type RemoteRefMut<'a> = Remote<&'a mut Repository>;

And then I pretty much just replaced all occurrences of Remote<'_> to RemoteRef<'_>.

What I like about this is that instead of

impl RemoteRef<'_> {
    pub fn save_to(&self, config: &mut git_config::File<'static>) -> Result<(), Error> {/*…*/}
}

we could e.g. have

impl RemoteRefMut<'_> {
    pub fn save(&self) -> Result<(), Error> {/*…*/}
}

Which will save VIA the given repository.

[Byron]

Saving remotes is currently a bit cumbersome as all changes remain in memory. Here is a function where that is done though as part of a clone. It's planned to improve this once there is a mechanism to easily write back changes to git_config::File.

What if, instead of using a lifetime, we just used a generic in place of a specific repository type, like so:

There was a time when this was the case. It was complicated and ultimately not what would work for a high-level crate like git-repository.
There is the notion of detached objects which exist in select cases, like ObjectDetached. For everything else, the idea is to liberally clone Repository instances, and use it as a handle to everything else, to be discarded after an operation is done. This is useful to adjust caches or other settings to be optimal for a particular algorithm, or for dealing with multiple threads. Other usage patterns might emerge over time that may be improved by having detached versions of other types, like RemoteDetached, but I didn't encounter them nor is such a case provided here.