Simple Git Assistant is a desktop application with a graphical user interface (GUI) designed to simplify the execution of common Git commands. It was created with the aim of making Git more accessible, especially for those who prefer a visual approach or are new to version control. The application provides a categorized list of Git commands, allows specifying input when necessary, and displays the output directly in the interface.
Current version: v5.0 - Upstream Push Management
This application is developed using the wxPython library. wxPython is known for using the native widgets of the underlying operating system, which generally ensures a good level of accessibility for visually impaired users who use screen readers and other assistive technologies to interact with desktop applications. The interface is designed to be navigable via keyboard as well.
The application will attempt to use your system's default language. Currently, it includes support for the following languages:
- English
- Italian
- Spanish
- French
- German
- Russian
If your system language is one of these and the corresponding translation file is present, the application will display in that language. Otherwise, it will default to Italian (the original language of the strings in the source code if no other translation is found).
- Git: It is essential to have Git installed correctly on your system, and its executable directory must be included in the system's PATH environment variable. The application checks for Git's presence at startup and reports any issues.
-
Selecting the Repository Folder:
- Upon startup, the application sets the current directory it was launched from as the working folder.
- It is possible (and often necessary) to specify the path to your local Git repository folder using the "Path" field and the "Browse..." button. Many Git commands require being executed within a valid Git repository.
-
Navigating and Selecting Commands:
- Git commands are organized into categories within a tree structure.
- Press the right arrow key or click on a category to expand it and view the commands within, or the left arrow key to collapse it.
- When selecting a command with the arrow keys (or with a single click), a brief description of its function will appear in the status bar at the bottom of the window.
- For more detailed information about a selected category or command, press the spacebar: a dialog box with the full description will open.
-
Executing a Command:
- To execute a command, navigate to it using the up/down arrow keys to select it, and then press the Enter key or double-click it in the tree structure.
- If the selected command requires user input (e.g., a URL to clone, a commit message, a branch name, etc.), a specific dialog box will appear. Follow the instructions and enter the required value.
- For some commands that can have a significant or potentially destructive impact on the repository (such as
reset --hardor forced deletions), the application will request additional confirmation before proceeding.
-
Viewing the Output:
- The output generated by the execution of the Git command (including success messages, information, warnings, or errors) will be displayed in real-time in the "Command Output" text area at the bottom of the interface. To reach it with the keyboard, simply press the Tab key.
Below are the categories of commands available in the Git Assistant:
Fundamental commands to start, clone, configure ignored files, and check the general status of the repository.
- Clone a repository (in the current folder): Clones a remote repository specified by the URL into a new subfolder within the currently selected 'Repository Folder'. Useful for starting work on an existing project. (Requires: Repository URL)
- Initialize a new repository here: Creates a new empty Git repository in the specified 'Repository Folder'. This is the first step to start a new project under version control.
- Add folder/file to ignore to .gitignore: Allows selecting a folder or file to add to the
.gitignorefile. Files and folders listed in.gitignoreare ignored by Git and will not be tracked or committed. - Check repository status: Shows the current status of the working directory and staging area. Indicates which files have been modified, which are staged (ready for commit), and which are not tracked by Git.
Commands to view differences, add files to the staging area, create and modify commits, and inspect history.
- View unstaged changes (diff): Shows changes made to tracked files that have not yet been added to the staging area (i.e., before 'git add'). Useful for reviewing changes before preparing them for a commit.
- View staged changes (diff --staged): Shows changes that have been added to the staging area and are ready to be included in the next commit. Useful for a final review before committing.
- Add all changes to the staging area: Adds all current changes (new, modified, deleted files) in the working directory to the staging area, preparing them for the next commit. Also used to mark merge conflicts as resolved.
- Create a commit (save changes): Saves a snapshot of the changes present in the staging area to the local repository. Each commit has a descriptive message. To complete a merge, leave the message empty if Git proposes one. (Requires: Commit Message)
- Rename last commit (amend): Modifies the message and/or files of the last commit. WARNING: Do not use if the commit has already been pushed to a shared repository, unless you know exactly what you are doing (requires a forced push and can create problems for collaborators). (Requires: New message for the last commit)
- Show details of a specific commit: Shows detailed information about a specific commit, including author, date, commit message, and changes introduced. (Requires: Commit hash, tag, or reference)
- View commit history (custom number): Shows the commit history. You can specify how many commits to display. The format is compact and shows the branch structure. (Requires: Number of commits to display)
Commands for branch management (creation, viewing, switching, merging, deletion) and tags.
- View all branches (local and remote): Lists all local branches and all tracked remote branches.
- Check current branch: Shows the name of the Git branch you are currently working on.
- Create new branch (without switching): Creates a new local branch based on the current commit, but does not automatically switch to it. (Requires: Name of the new branch)
- Create and switch to a new branch: Creates a new local branch and immediately switches to it. (Requires: Name of the new branch)
- Switch to an existing branch: Switches you to another existing local branch. (Requires: Name of the branch)
- Merge specified branch into current (merge): Integrates changes from another branch into your current branch. If there are conflicts, they will be reported, and you can choose a resolution strategy. (Requires: Name of the branch to merge)
- Delete local branch (safe, -d): Deletes a local branch only if it has been fully merged. If it fails because it's not merged, you will be asked if you want to force it. (Requires: Name of the local branch to delete; requires confirmation)
- Delete local branch (forced, -D): WARNING: Forcibly deletes a local branch, even if it contains unmerged commits. (Requires: Name of the local branch to delete; requires confirmation and maximum attention)
- Create new Tag (lightweight): Creates a lightweight tag to mark a specific point in history, usually used for releases (e.g., v1.0). It can be applied to the current commit (HEAD) or a specific commit. (Requires: Tag Name [opt: CommitHash/Ref])
Commands for interacting with remote repositories: download (fetch/pull), send (push), configure remotes, and delete remote branches.
- Download from remote 'origin' (fetch): Downloads all updates (commits, branches, tags) from the specified remote repository (usually 'origin') but does not automatically merge these changes into your local work.
- Download changes from server and merge (pull): Equivalent to a 'git fetch' followed by a 'git merge' of the tracked remote branch into your current local branch.
- Send changes to the server (push): Sends commits from your local branch to the corresponding remote repository.
- Add remote repository 'origin': Connects your local repository to a remote repository. (Requires: Remote repository URL)
- Modify URL of remote repository 'origin': Modifies the URL of an existing remote repository. (Requires: New URL of the remote repository)
- Check configured remote addresses: Shows the list of configured remote repositories.
- Delete remote branch ('origin'): Deletes a branch from the 'origin' remote repository. (Requires: Name of the branch on 'origin'; requires confirmation)
Commands to temporarily set aside uncommitted changes.
- Temporarily save changes (stash): Sets aside uncommitted changes to clean the working directory.
- Apply latest changes from stash (stash pop): Applies changes from the last stash and removes it from the list.
Commands for searching text within project files and for finding specific files tracked by Git.
- Search text in files (git grep): Searches for a text pattern (case-insensitive) in Git-tracked files. Shows filename and line number of matches. (Requires: Text to search)
- Search files in project (tracked by Git): Lists files tracked by Git. You can provide a pattern (case-insensitive, searches as substring) to filter results. Leave empty to see all files. (Optional input: Filename pattern)
Powerful commands to undo changes, restore files to previous versions, or reset the repository state. These actions can lead to data loss if not used correctly.
- Discard changes on specific file (restore): Discards changes not yet staged for a specific file (selected via dialog), restoring it to the state of the last commit.
- Overwrite files with commit and clean (checkout . && clean -fd): WARNING: Overwrites files with versions from the commit AND REMOVES untracked files/directories. (Requires: Commit hash/reference; requires confirmation and maximum attention)
- Restore modified files and clean untracked files: Discards changes in tracked files and removes untracked files/directories. (Requires confirmation and maximum attention)
- Discard local changes (reset --hard HEAD): Resets the current branch to the last commit, discarding all uncommitted local changes. (Requires confirmation and maximum attention)
- Abort merge attempt (abort): Aborts a failed merge attempt due to conflicts, returning the repository to the state before the merge. (Requires confirmation)
- Inspect specific commit (checkout - detached HEAD): Switches you to a specific commit in a 'detached HEAD' state. New changes will not belong to any branch unless you create one. (Requires: Commit hash/reference; requires confirmation)
- Reset local branch to remote version (origin/branch-name): WARNING: Resets the CURRENT local branch to the state of the remote branch 'origin/'. Local changes and unpushed commits will be LOST. (Requires: Remote branch name; requires extremely dangerous confirmation)
- Reset current branch to specific commit (reset --hard): MAXIMUM ATTENTION: Moves the current branch pointer to the specified commit and LOSES ALL subsequent local commits and changes. (Requires: Commit hash/reference; requires extremely dangerous confirmation)
The assistant includes specific logic to improve the user experience in certain situations:
- Push on Branch Without Remote Upstream: If you attempt to
pusha local branch that does not yet have a corresponding remote upstream branch configured (common "no upstream branch" error), the application detects this situation. It will ask the user if they want to automatically set the remote branch as upstream and re-execute the push with the commandgit push --set-upstream origin <branch-name>. - Merge Conflict Management: During a
mergeoperation (Merge specified branch into current), if file conflicts are detected, the application:- Notifies the user and shows the conflicting files.
- Offers several options to proceed:
- Resolve conflicts manually: The user will need to edit the files manually, then use the "Add all changes to the staging area" and "Create a commit" commands.
- Use current branch version (
--ours): For all conflicting files, the changes from the branch you are working on (HEAD) will be kept. - Use incoming branch version (
--theirs): For all conflicting files, the changes from the branch you are trying to merge will be accepted. - Abort the merge attempt (
git merge --abort): Restores the state before the merge attempt.
- Safe Deletion of Local Branches: If you try to delete a local branch using the safe option (
Delete local branch (safe, -d)) and the branch contains commits not yet integrated (merged) into other branches, Git will prevent the deletion. The assistant will intercept this warning and ask the user if they want to force the deletion of the branch (equivalent togit branch -D <branch-name>), warning about potential loss of work. - Amending Last Commit and Forced Push: After modifying the last commit with the
Rename last commit (amend)command, the application will ask if you want to attempt apush --forceto 'origin'. A warning will be displayed that such an operation overwrites history on the server and can cause problems for collaborators. - Interaction with
.gitignore: TheAdd folder/file to ignore to .gitignorecommand allows interactive selection of a file or folder. The application handles:- Converting the absolute path to a repository-relative path.
- Adding a trailing slash
/if it's a folder. - Checking if the item is already present in the
.gitignorefile to avoid duplicates. - Ensuring there is a newline before adding the new line if the
.gitignorefile exists and is not empty.
- Search Files in Project (
git ls-files): Besides listing all Git-tracked files, this command allows entering a pattern to filter results (e.g.,*.py,docs/*). The application first checks if the selected directory is a valid Git repository. - Automatic Path Update After Clone: After successfully cloning a repository, the Git Assistant will automatically update the "Repository Folder Path" field to point to the newly created folder.
To create a standalone executable file (e.g., a single .exe file on Windows) from the assistente-git.py source code, you can use PyInstaller. Open a terminal or command prompt in the directory containing the Python file and run:
pyinstaller --onefile --windowed --name AssistenteGit assistente-git.py