Oxidize GitButler

[Byron]

Used Git2 Features

The list is probably not completely exhaustive, omitting smaller features intentionally as they are covered, and focussing on the bigger picture.

• refspecs
• init (and fail if present already) , bare or non-bare
• get configuration by scope
• set configuration by scope and write it back while keeping comments/nonedestructively
  • writes are convenient through high-level API
• read and traverse git configuration
• fetch a remote (and handle credentials like Git would)
• merge-base octopus to prevent surprising behaviour - make sure this is made available in virtual merge base handling as well.
• full support for git-config, includeIf and hasconfig
• merge multiple commits into one, with multi-mergebase support (see checkout_branches…())
  • provide merged index
  • merge submodules
• tree-from-worktree, but fast using full status
• write loose objects uncompressed, see the issue around big files
• Performance: apply a patch efficiently (replace diffy, use native hunks maybe?)
• in-memory .gitignore rules, so that any user of excludes gets these automatically
• sanitization as part of refname validation (just like Git offers, see this issue)
• add ODB alternates
• add submodule
• use git-remote helpers, i.e. codecommit or rad.
• 'is descendant of' query
• merge base query
• create a new remote (primitives exist, but there is no higher-level method for it)
• rename reference (there is no shortcut for this, just lower-level primitives delete+create)
• git add . - with proper worktree filtering (add currently unsupported, but worktree filter could help already)
• diff tree to workdir (primitives exist)
• merge trees
• rebase
• find remotes
• find head and deal with refs in general (peeling, etc)
• diff tree with tree
• reset
• find objects and deal with them in various ways
• revwalk (even though it's still to be seen if the algorithm is what's expected, see the topo-walk discussion
• query excludes/.gitignore - but should be performed on all available paths
• get the index
• cherry pick
• create a new commit
• create a new signed commit (and respect these settings even when rebasing)
• build a new tree by API
• obtain remote branch names in various flavours
• git status (primitives exist, WIP)
• checkout head/index/tree (checkout exists, but this needs 'reset' functionality)
• optionally run hooks on commit (and other events maybe, just like Git)
  • keep in mind what GUI applications would do, and maybe document how to solve the issue that the env isn't the same as in the terminal. See Use default shell for git-hooks instead of bash extrawurst/gitui#2317 .
• walk a tree
• index to tree
• tree to index
• complete diff based on git status equivalent (primitives exist)

Wanted

What follows is prominent issues from the GitButler tracker.

• Azure DevOps cloning support.
• Windows Support
  • natively supported
  • there may be rough edges around program and hook invocations, to be smoothed out of time (probably this is about more than Git though, currently unclear)
• SSH Authentication
  • ssh is used, which is exactly what git does.
  • on Windows, there is no native ssh transport yet which might be worse than git2 right now. See Built-in SSH transport #1246 for more.
• Git LFS support
  • checkouts will call filter programs, thus checkout LFS files
  • diffs will apply all diff-related features and handle LFS files correctly
  • additions, i.e. git add, aren't possible yet, but when they are they will call worktree filters
• Opening Submodules
  • Works in theory, even though it's unclear what's happening that it's not working currently
• Local ref handling
  • Making these entirely transparent to git log --all might be possible with namespaces. Maybe worth a try.
  • This is feasible once gitoxide is used everywhere - each repository instance created needs to have the GitButler namespace set then, at least those that read or write GitButler references.
  • However, using these would probably yield no benefit over how it's done currently.

Here is the repo: https://github.com/gitbutlerapp/gitbutler

Shortcomings that might be a problem

• copy detection differs from git weirdly #1524

Guiding Principles

After our in-person meet, I kept mentioning a few driving principles that I find valuable to keep in mind when planning the next steps.

• The transition to gitoxide should be step-wise.
• Each step should yield meaningful, perceivable value for the user of the application.
• It's OK to not reach goals directly, i.e. use intermediate mechanisms that help now, knowing that they will be removed later.

gitoxide is an implementation detail, but ultimately it will drive down the implementation complexity of the application while improving its performance and compatibility.

Notes on issues

From time to time, one can look into issues that are waiting for feedback.

Try to fix this when converting to gitoxide

Check the `gitoxide label for more.

Big Problems

Architecturally, there might be issues in resolving these:

• Issues applying a branch with conflicts gitbutlerapp/gitbutler#3319 (resolving conflicts with the usual set of tools)

Requested features

Roughly in order of effort-for-value

• Open gitbutler in a repository from the terminal with gitbutler . (see this comment)
• Better handling of being offline (see this issue as example)

Authentication

Use this label to list them all.

Profile Picutures

• Profile picture doesn't get updated at all places gitbutlerapp/gitbutler#2589
• Adding the Linux Kernel as project takes more than an hour to complete gitbutlerapp/gitbutler#3512

Pre-commit hooks

• View hook failure logs gitbutlerapp/gitbutler#2551
• View hook failure logs gitbutlerapp/gitbutler#2551

[darleybarreto]

Hey Sebastian,

Thanks for this! I was planning on doing this discovery later this week, because I'm off due to Carnival. I actually opened a discussion in the repo.

[Byron]

Thanks for kicking this off and for pointing to the original discussion! It helped me to understand what's going on as I was a little confused - now I see that a migration is happening to the -git crate and all makes sense.

I was pretty quick in creating this issue and I welcome you to double-check, or ask for clarification where you see fit or need. This can only make it better.

[krlvi]

Thank you @Byron for this! It was such a treat meeting you, and I am so excited about oxidising GitButler :)
I fully agree about the general principles that you outlined, it's very much how we like to approach problems too.

[Qix-]

add ODB alternates

While this is something Gitoxide should of course support, we're actually moving away from needing this long-term.

on Windows, there is no native ssh transport yet which might be worse than git2 right now.

Check out https://docs.rs/russh - they've been great maintainers and I used to use this crate for testing SSH stuff locally. Might work as a native transport. It's a maintained, spruced up version of Pijul's thrussh.

[Byron]

Thanks for the suggestions! I have just linked the gitoxide native #1246 issue, and believe that also lists russh as very strong candidate.