kicad_git_common.h

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright The KiCad Developers, see AUTHORS.TXT for contributors.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 3
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
#ifndef _GIT_COMMON_H_
#define _GIT_COMMON_H_
 
#include <git/git_backend.h>
#include <git/git_compare_handler.h>
#include <git/kicad_git_errors.h>
#include <git/kigit_known_hosts.h>
#include <import_export.h>
 
#include <git2.h>
#include <atomic>
#include <chrono>
#include <functional>
#include <mutex>
#include <optional>
#include <set>
#include <utility>
#include <vector>
 
#include <wx/datetime.h>
#include <wx/string.h>
 
class LIBGIT_BACKEND;
struct KIGIT_AUTH_ATTEMPT;
 

struct KIGIT_ERROR_INFO
{
    int      klass = 0; 
    int      code = 0;  
    wxString message;
};
 
 
// One entry in the commit history, as shown by the advanced git window's History page.
struct KIGIT_COMMIT_INFO
{
    wxString              hash;    
    wxString              summary; 
    wxString              author;  
    wxString              email;   
    wxDateTime            when;    
    std::vector<wxString> refs;    
};
 
 
// What the Stashes page's detail pane shows about one stash.
struct KIGIT_STASH_DETAIL
{
    bool                  found = false;
    wxString              message;  
    wxString              branch;   
    wxString              baseHash; 
    wxDateTime            when;
    std::vector<wxString> files; 
};
 
 
// A local or remote branch and its tip commit.
struct KIGIT_BRANCH_INFO
{
    wxString   name;
    bool       isRemote = false;
    bool       isCurrent = false;
    wxString   tipHash; 
    wxString   message; 
    wxDateTime when;    
};
 
 
// Commit counts between two references.
struct KIGIT_AHEAD_BEHIND
{
    size_t ahead = 0;  
    size_t behind = 0; 
};
 
 
// What the Branches page's detail pane shows about one branch.
struct KIGIT_BRANCH_DETAIL
{
    bool       found = false;
    wxString   name;
    wxString   tipHash;
    wxDateTime when;
    wxString   author;
    wxString   email;
    wxString   message;
    wxString   upstream; 

    std::optional<KIGIT_AHEAD_BEHIND> divergence;
};
 
 
// Which commits the History page walks.
struct KIGIT_HISTORY_FILTER
{
    wxString branch; 
    wxString search; 
    wxString path;   
};
 
 
// One file a commit changed, with its line counts against the parent.
struct KIGIT_COMMIT_FILE
{
    wxString                  path;
    wxString                  oldPath; 
    KIGIT::FILE_CHANGE_STATUS status = KIGIT::FILE_CHANGE_STATUS::MODIFIED;
    int                       added = 0;
    int                       removed = 0;
    bool                      binary = false;
};
 
 
// Everything the History page's detail pane shows about one commit.
struct KIGIT_COMMIT_DETAIL
{
    bool                           found = false;
    wxString                       hash; 
    wxString                       shortHash;
    wxString                       message; 
    wxString                       author;
    wxString                       email;
    wxDateTime                     when;
    std::vector<wxString>          parents; 
    std::vector<wxString>          refs;    
    std::vector<KIGIT_COMMIT_FILE> files;
    int                            added = 0;
    int                            removed = 0;
};
 
 
// One entry in the stash list, as shown by the advanced git window's Stashes page.
struct KIGIT_STASH_INFO
{
    size_t     index = 0; 
    wxString   id;        
    wxString   message;   
    wxDateTime when;      
};
 
 
// One entry in the tag list, as shown by the advanced git window's Tags page.
struct KIGIT_TAG_INFO
{
    wxString   name;    
    wxString   hash;    
    wxString   summary; 
    wxDateTime when;    
};
 
 
// What the Tags page's detail pane shows about one tag.
struct KIGIT_TAG_DETAIL
{
    bool       found = false; 
    wxString   name;          
    wxString   hash;          
    wxDateTime when;          
    wxString   author;        
    wxString   email;         
    wxString   message;       
};
 
 
// The kind of operation a repository can be left in the middle of.
enum class GitOperation
{
    None,
    Merge,
    Rebase,
    CherryPick,
    Revert,
    Other
};
 
 
// Outcome of restoring an old version as a new commit.
enum class RestoreResult
{
    Restored,       
    AlreadyCurrent, 
    Dirty,          
    Error           
};
 
 
// Each side of a conflicted file, extracted to a temp file. A side that does not exist is empty.
struct KIGIT_CONFLICT_SIDES
{
    wxString path;                
    wxString ancestorFile;        
    wxString oursFile;            
    wxString theirsFile;          
    bool     hasAncestor = false; 
    bool     hasOurs = false;     
    bool     hasTheirs = false;   
};
 

class APIEXPORT KIGIT_COMMON
{
 
public:
    KIGIT_COMMON( git_repository* aRepo, const wxString& aProjectPath = wxEmptyString );
    KIGIT_COMMON( const KIGIT_COMMON& aOther );
    ~KIGIT_COMMON();
 
    git_repository* GetRepo() const;
 
    void SetRepo( git_repository* aRepo )
    {
        m_repo = aRepo;
    }
 
    wxString GetCurrentBranchName() const;

    wxString GetHeadCommitId() const;

    std::vector<KIGIT_BRANCH_INFO> GetBranches() const;
 
    // One branch's tip commit and how it stands to the branch it tracks. Not found leaves the
    // result's found flag clear.
    KIGIT_BRANCH_DETAIL GetBranchDetail( const wxString& aBranch ) const;

    std::vector<wxString> GetProjectDirs();

    std::pair<std::set<wxString>,std::set<wxString>> GetDifferentFiles() const;
 
    enum class GIT_STATUS
    {
        GIT_STATUS_UNTRACKED,
        GIT_STATUS_CURRENT,
        GIT_STATUS_MODIFIED,        // File changed but not committed to local repository
        GIT_STATUS_ADDED,
        GIT_STATUS_DELETED,
        GIT_STATUS_BEHIND,          // File changed in remote repository but not in local
        GIT_STATUS_AHEAD,           // File changed in local repository but not in remote
        GIT_STATUS_CONFLICTED,
        GIT_STATUS_IGNORED,
        GIT_STATUS_LAST
    };
 
    enum class GIT_CONN_TYPE
    {
        GIT_CONN_HTTPS = 0,
        GIT_CONN_SSH,
        GIT_CONN_LOCAL,
        GIT_CONN_LAST
    };

    struct REMOTE_URL
    {
        wxString      url; 
        wxString      username;
        wxString      password;
        wxString      hostname;
        int           port = 0; 
        GIT_CONN_TYPE connType = GIT_CONN_TYPE::GIT_CONN_LOCAL;
    };
 
    static REMOTE_URL ParseRemoteURL( const wxString& aURL );
 
    wxString GetUsername() const
    {
        std::lock_guard<std::mutex> lock( m_credentialsMutex );
        return m_username;
    }
 
    wxString GetPassword();
    GIT_CONN_TYPE GetConnType() const;

    void SetConnType( GIT_CONN_TYPE aConnType );
 
    void SetUsername( const wxString& aUsername )
    {
        std::lock_guard<std::mutex> lock( m_credentialsMutex );
        m_username = aUsername;
        m_secretFetched = false;
    }
 
    void SetPassword( const wxString& aPassword )
    {
        std::lock_guard<std::mutex> lock( m_credentialsMutex );
        m_password = aPassword;
        m_secretFetched = true;
    }
    void SetSSHKey( const wxString& aSSHKey );

    wxString GetSSHKey() const;

    wxString GetFirstOfferedSSHKey() const;

    struct CREDENTIAL_IDENTITY
    {
        wxString      remote;
        GIT_CONN_TYPE connType = GIT_CONN_TYPE::GIT_CONN_LOCAL;
        wxString      username;
    };

    struct PROMPTED_CREDENTIALS
    {
        GIT_CONN_TYPE           connType = GIT_CONN_TYPE::GIT_CONN_LOCAL;
        std::optional<wxString> username;
        wxString                password;
        wxString                sshKey;
    };
 
    CREDENTIAL_IDENTITY GetCredentialIdentity() const;

    bool ApplyPromptedCredentials( const CREDENTIAL_IDENTITY& aFor, const PROMPTED_CREDENTIALS& aEntered );
 
    // Holds a temporary variable that can be used by the authentication callback
    // to remember which types of authentication have been tested so that we
    // don't loop forever.
    std::atomic<unsigned>& TestedTypes() { return m_testedTypes; }

    bool HasLocalCommits() const;

    bool HasUpstreamCommits() const;

    bool IsPullRebaseConfigured() const;

    bool IsHeadDetached() const;

    std::optional<size_t> GetUnmergedCommitCount( const wxString& aBranch ) const;
 
    // True when tracked files hold uncommitted changes, staged or not. Untracked files do not
    // count: a merge leaves them alone. aReadOk distinguishes a clean tree from a failed read.
    bool HasUncommittedTrackedChanges( bool* aReadOk = nullptr ) const;
 
    // The full messages of the newest commits from HEAD, newest first, with repeats dropped.
    std::vector<wxString> GetRecentCommitMessages( size_t aMax ) const;
 
    // The most recent commits aFilter selects, newest first, up to aMax of them.
    std::vector<KIGIT_COMMIT_INFO> GetRecentCommits( size_t aMax = 50, const KIGIT_HISTORY_FILTER& aFilter = {} ) const;
 
    // One commit in full, with the files it changed against its first parent. A root commit's
    // files all count as added. Not found leaves the result's found flag clear.
    KIGIT_COMMIT_DETAIL GetCommitDetail( const wxString& aHash ) const;
 
    // The full message of the commit HEAD points at, body and trailers included. The amend
    // prefill uses this, so accepting the suggestion does not truncate the message to its
    // first line.
    wxString GetLastCommitMessage() const;
 
    // The stashes in the repository, in the order git reports them (newest first).
    std::vector<KIGIT_STASH_INFO> GetStashes() const;
 
    // One stash in full, by its commit id. Not found leaves the result's found flag clear.
    KIGIT_STASH_DETAIL GetStashDetail( const wxString& aId ) const;
 
    // The tags in the repository, each resolved to the commit it points at.
    std::vector<KIGIT_TAG_INFO> GetTags() const;
 
    // One tag in full. Not found leaves the result's found flag clear.
    KIGIT_TAG_DETAIL GetTagDetail( const wxString& aName ) const;

    bool IsHeadUnborn() const;
 
    // The caller holds the action lock, as with the query methods above.
    // Create aName at the tip of aFrom, a local or remote branch, or at HEAD when aFrom is empty.
    bool CreateBranch( const wxString& aName, const wxString& aFrom = wxEmptyString );

    bool StartUnbornBranch( const wxString& aName );
    bool DeleteBranch( const wxString& aName );

    bool StashSave( const wxString& aMessage );
    bool StashApply( size_t aIndex );
    bool StashPop( size_t aIndex );
    bool StashDrop( size_t aIndex );
 
    // Tag HEAD. With a message the tag is annotated and carries it, otherwise it is lightweight.
    bool CreateTag( const wxString& aName, const wxString& aMessage = wxEmptyString );
    bool DeleteTag( const wxString& aName );
    bool CheckoutTag( const wxString& aName );
 
    bool AddRemote( const wxString& aName, const wxString& aUrl );
    bool SetRemoteUrl( const wxString& aName, const wxString& aUrl );
    bool RemoveRemote( const wxString& aName );
 
    bool SetUserConfig( const wxString& aName, const wxString& aEmail );

    bool GetMergeConflicts( const wxString& aStageDir, wxString& aHeadOid, wxString& aTheirsOid,
                            std::vector<KIGIT_CONFLICT_SIDES>& aConflicts, wxString& aError );

    RestoreResult RestoreVersion( const wxString& aCommitHash, KIGIT_ERROR_MESSAGE& aError );

    bool DiscardChanges( const std::vector<wxString>& aPaths, wxString& aError );

    bool IsPathInHead( const wxString& aPath );

    bool IsPathConflicted( const wxString& aPath ) const;

    bool IsOperationInProgress() const;

    GitOperation OperationInProgress() const;

    bool AbandonOperation( wxString& aError );

    MergeCommitResult CreateMergedCommit( const wxString& aExpectedHeadOid, const wxString& aTheirsOid,
                                          const std::vector<std::pair<wxString, wxString>>& aResolvedFiles,
                                          KIGIT_ERROR_MESSAGE&                              aError );
 
    // Returns true if the repository has a remote that can be pushed to pulled from
    bool HasPushAndPullRemote() const;
 
    // Updates the password and remote information for the repository given the current branch
    void UpdateCurrentBranchInfo();

    void SyncRemoteUrl( const wxString& aRawUrl );

    void FollowRewrittenUrl( const wxString& aRawUrl );
 
    wxString GetGitRootDirectory() const;
 
    wxString GetRemotename() const;

    std::vector<std::pair<wxString, wxString>> GetRemotes() const;
 
    // When the repository last fetched, from any remote. Invalid when it never has.
    wxDateTime GetLastFetchTime() const;
 
    // Lines added and removed in the working tree against HEAD, new files included. Only for
    // aPaths, relative to the repository root, so the count matches the list beside it.
    std::pair<int, int> GetWorkingTreeLineStats( const std::set<wxString>& aPaths ) const;

    wxString GetRemoteNameOrDefault() const;

    void SetProjectDir( const wxString& aProjectDir ) { m_projectDir = aProjectDir; }

    wxString GetProjectDir() const;

    std::optional<wxString> GetProjectPrefix() const;

    void SetAttachError( const wxString& aError, const wxString& aTrustCommand = wxEmptyString )
    {
        m_attachError = aError;
        m_attachTrustCommand = aTrustCommand;
    }
 
    const wxString& GetAttachError() const { return m_attachError; }

    const wxString& GetAttachTrustCommand() const { return m_attachTrustCommand; }
 
    void ResetNextKey()
    {
        std::lock_guard<std::mutex> lock( m_credentialsMutex );
        m_nextPublicKey = 0;
    }

    wxString GetNextPublicKey();
 
    void SetRemote( const wxString& aRemote )
    {
        {
            std::lock_guard<std::mutex> lock( m_credentialsMutex );
            m_remote = aRemote;
            m_password.clear();
            m_secretFetched = false;
            updateConnectionTypeUnlocked();
        }
 
        // Gathers the keys now, or the first transfer's sync would drop a key chosen after this
        SyncRemoteUrl( aRemote );
    }
 
    wxString GetRemote() const
    {
        std::lock_guard<std::mutex> lock( m_credentialsMutex );
        return m_remote;
    }

    int HandleSSHKeyAuthentication( git_cred** aOut, const wxString& aUsername, KIGIT_AUTH_ATTEMPT& aAttempt );
 
    int HandlePlaintextAuthentication( git_cred** aOut, const wxString& aUsername );
 
    int HandleSSHAgentAuthentication( git_cred** aOut, const wxString& aUsername );

    static wxString GetLastGitError();

    static KIGIT_ERROR_INFO GetLastGitErrorInfo( int aCode );

    using CANCEL_TOKEN = std::shared_ptr<std::atomic<bool>>;
 
    static CANCEL_TOKEN NewCancelToken() { return std::make_shared<std::atomic<bool>>( false ); }

    class OPERATION_GUARD
    {
    public:
        OPERATION_GUARD( KIGIT_COMMON* aCommon, const CANCEL_TOKEN& aToken ) :
                m_common( aCommon ),
                m_token( aToken )
        {
            std::lock_guard<std::mutex> lock( m_common->m_operationMutex );
            m_common->m_activeCancel = m_token;
 
            // A shutdown asked for before this operation reached the lock still applies to it.
            if( m_token && m_common->m_shutdown )
                m_token->store( true );
        }

        ~OPERATION_GUARD()
        {
            std::lock_guard<std::mutex> lock( m_common->m_operationMutex );
 
            if( m_common->m_activeCancel == m_token )
                m_common->m_activeCancel.reset();
        }
 
        OPERATION_GUARD( const OPERATION_GUARD& ) = delete;
        OPERATION_GUARD& operator=( const OPERATION_GUARD& ) = delete;
 
    private:
        KIGIT_COMMON* m_common;
        CANCEL_TOKEN  m_token;
    };

    bool IsShuttingDown() const
    {
        std::lock_guard<std::mutex> lock( m_operationMutex );
        return m_shutdown;
    }

    void SetShuttingDown( bool aCancel )
    {
        std::lock_guard<std::mutex> lock( m_operationMutex );
        m_shutdown = aCancel;
 
        if( aCancel && m_activeCancel )
            m_activeCancel->store( true );
    }

    int SSHPortFor( const wxString& aHost ) const;
 
    std::unique_lock<std::mutex> TryLockAction()
    {
        return std::unique_lock<std::mutex>( m_gitActionMutex, std::try_to_lock );
    }

    static constexpr std::chrono::milliseconds ACTION_LOCK_WAIT{ 2000 };

    std::unique_lock<std::mutex> TryLockActionFor( std::chrono::milliseconds aWait );
 
    std::unique_lock<std::mutex> LockAction() { return std::unique_lock<std::mutex>( m_gitActionMutex ); }
 
    // Views showing working-tree state register here, so a commit, push or pull in one of them
    // refreshes the others. UI thread only, so the list needs no lock.
    void AddRefreshListener( void* aOwner, std::function<void()> aCallback );
    void RemoveRefreshListener( void* aOwner );
    void NotifyRefreshListeners();
 
protected:
    git_repository* m_repo;
 
    wxString m_projectDir;  // Repository working directory preserving symlinks
    wxString m_projectPath; // Project directory captured when the session was created
    wxString m_attachError;
    wxString m_attachTrustCommand;
 
    GIT_CONN_TYPE m_connType;
    wxString m_remote;      // This is the full connection string
    wxString m_urlUsername; // The username m_remote was parsed with, which HTTPS strips from it
    wxString m_hostname;    // This is just the hostname without the protocol, username, or password
    int      m_port = 0;    // The port m_remote names, 0 when it names none and -1 when it is not valid
    wxString m_username;
    wxString m_password;
 
    std::atomic<unsigned> m_testedTypes;
 
    std::mutex m_gitActionMutex;

    mutable std::mutex m_credentialsMutex;
 
    std::vector<std::pair<void*, std::function<void()>>> m_refreshListeners;
 
    // Make git handlers friends so they can access the mutex
    friend class GIT_PUSH_HANDLER;
    friend class GIT_PULL_HANDLER;
    friend class GIT_CLONE_HANDLER;
    friend class LIBGIT_BACKEND;
 
private:
    std::optional<KIGIT_AHEAD_BEHIND> compareRefs( const git_reference* aBranch, const git_reference* aBase ) const;
 
    CANCEL_TOKEN ActiveCancelToken() const
    {
        std::lock_guard<std::mutex> lock( m_operationMutex );
        return m_activeCancel;
    }

    wxString remoteNameWithoutUpstream() const;
 
    void updatePublicKeys();

    void rebuildPublicKeysUnlocked();
    void updateConnectionType();

    void updateConnectionTypeUnlocked();
 
    std::vector<wxString> m_discoveredKeys; // Gathered for m_publicKeysHost, without the project key
    std::vector<wxString> m_publicKeys;
    wxString m_publicKeysHost; // The host m_publicKeys was gathered for
    wxString m_projectSSHKey;  // Kept when its file is missing, so the setting is not lost
    int m_nextPublicKey;
    bool m_secretFetched;

    mutable std::mutex m_operationMutex;
    CANCEL_TOKEN       m_activeCancel;
    bool               m_shutdown = false;
 
    // Create a dummy flag to tell if we have tested ssh agent credentials separately
    // from the ssh key credentials. Our own bit, so it must clear every git_credential_t
    // value. The highest is GIT_CREDENTIAL_SSH_MEMORY at 1 << 6.
    static const unsigned KIGIT_CREDENTIAL_SSH_AGENT = 1u << ( sizeof( unsigned ) * 8 - 1 );
};
 
extern "C" APIEXPORT int  progress_cb( const char* str, int len, void* data );
extern "C" APIEXPORT void clone_progress_cb( const char* str, size_t len, size_t total, void* data );
extern "C" APIEXPORT int transfer_progress_cb( const git_transfer_progress* aStats, void* aPayload );
extern "C" APIEXPORT int update_cb( const char* aRefname, const git_oid* aFirst, const git_oid* aSecond,
                                    void* aPayload );
extern "C" APIEXPORT int push_transfer_progress_cb( unsigned int aCurrent, unsigned int aTotal,
                                                    size_t aBytes, void* aPayload );
extern "C" APIEXPORT int push_update_reference_cb( const char* aRefname, const char* aStatus,
                                                   void* aPayload );
 
extern "C" APIEXPORT int fetchhead_foreach_cb( const char*, const char*,
                                               const git_oid* aOID, unsigned int aIsMerge, void* aPayload );
extern "C" APIEXPORT int credentials_cb( git_cred** aOut, const char* aUrl, const char* aUsername,
                                         unsigned int aAllowedTypes, void* aPayload );

extern "C" APIEXPORT int certificate_check_cb( git_cert* aCert, int aValid, const char* aHost, void* aPayload );
 
 
class wxWindow;
 
 
namespace KIGIT
{

APIEXPORT bool IsPrivateKeyEncrypted( const wxString& aKeyText );
 

APIEXPORT wxWindow*& ActiveAdvancedGitWindow();
 

APIEXPORT git_tree* ResolveRefToTree( git_repository* aRepo, const wxString& aRef );
 

APIEXPORT std::vector<wxString> CompareBranchRefs( git_repository* aRepo );
 

APIEXPORT void CollectDiffDeltas( git_diff*                                           aDiff,
                                  const std::function<void( const git_diff_delta& )>& aCallback );

APIEXPORT wxString ComposeCommitMessage( const wxString& aSummary, const wxString& aDescription,
                                         const wxString& aSignOff );

APIEXPORT void SplitCommitMessage( const wxString& aMessage, wxString& aSummary, wxString& aDescription );

APIEXPORT wxString BranchNameError( const wxString& aName );

APIEXPORT wxString DecodeRepoText( const char* aText );

APIEXPORT wxString BusyMessage();
 
} // namespace KIGIT
 
 
#endif // _GIT_COMMON_H_