APLGit2
comes with a small set of user commands and functions designed to support the APL programmer while working on projects managed by Git.
APLGit2
runs on Windows, Linux and Mac OS.
Experience tells us that trying to support all sorts of Git commands from within APL is a recipe for trouble. For example, the Git command "checkout" should not be performed from within an APL session.
More complex stuff like Merge
, Push
and Pull
can quickly run into a problem without the user doing anything wrong, and when they do, you are stuck in the middle of something within the call that executed a Git command, leaving you in the dark about how far things got.
Therefore, APLGit2
offers only a limited number of useful commands from within APL while working on a project. For anything else we suggest using GitBash. APLGit2
makes this easy because ]APLGit2.OpenGitShell
opens a Git Bash within the current project (if there is just one open) or in the specified/selected project.
As a result, most commands provide information about the given project or an object within that project.
Noticeable exceptions are the methods Add
and Commit
. Note that you can execute Add
implicitly when executing Commit
; see there.
We strongly recommend using the Git Bash for anything beyond that. This approach has two significant advantages:
- Pretty much all help available on the Internet will provide solutions and examples for the Git Bash
- For exceptional problems / tasks you have to use the Git Bash anyway, so getting used to it has merits
All functions are also available via an API which lives in ⎕SE.APLGit2
. However, the API calls are more basic.
For example, the Commit
API function just does that: executing git commit
. On the other hand, the user command first checks whether the project is currently dirty, and if it is, it asks the user whether git add .
should be executed first. Also, it opens an edit window for the user to create a message in case the -m=
option is not set.
- The Git bash must be installed and available on the environment variable
%PATH%
- The Git config parameters
user.name
anduser.email
must be set
One function relies on you hosting your project(s) on GitHub: GetTagOfLatestRelease
All other commands are agnostic in this respect.
]APLGit2.*
works particularly well in conjunction with Cider, though this is not a requirement.
- If a single Cider project is open, APLGit2 will always act on that project if no folder is specified
- If multiple Cider projects are open, the user is asked which project to act on
However, with a project not managed by Cider, you must always specify a folder, either as an argument of a user command or by calling ]APLGit2.SetDefaultProject
.
Note that APLGit2
works only locally. It does not accept a URL pointing to GitHub.
APLGit2 can be installed as a Tatin package:
]Tatin.InstallPackages [tatin]aplgit2 [MyUCMDs]
This will make the user commands of APLGit2
available, but it will not establish the API. However, executing any of its user commands will force APLGit2
to load the API into ⎕SE
. For that, executing ]APLGIT2.Version
will do.
If you want the API to be available right from the start then please consult the article Dyalog User Commands.
User commands start with an ]
, API function don't.
]Add Execute the Git "Add" commands with the -A flag on "."
]AddGitIgnore Adds a file `.gitignore` to a path with defaults useful for APLers
]ChangeLog Takes an APL name and lists all commits the object was part of
]Commit Performs a commit on the current branch
]CompareCommits Takes two hashes and compares all changes between them
]Diff Returns files in the working directory that are different from HEAD
EstablishProject Works out the project to act on
]GetDefaultProject Returns the default project, if any
GetPathFromProjec Get the path on disk where the project specified lived
GetProjectFromPath Get the path in the workspace from the disk path of a project
]GetDefaultProject Returns namespace and folder of the current default project, if any
]GetTagOfLatestRelease Returns the tag of the latest release
]Init Initialises project with Git, including .gitignore & .gitattributes
]IsDirty Are there any uncommited changes?
]IsGitProject Returns "yes" or "no" depending on whether there is a ./.git folder
IsGitInstalled Checks whether Git is installed and retuns 1 in case it is
]ListBranches Lists all branches for a Git-managed project
]Log Returns the log of commits.\\
Methods Like `Public` plus comment in first line
]NoOfUntrackedFiles Returns the number of untracked files in a project or folder
]OpenGitShell Opens a Git shell for a Git-managed project
]RefLog Prints a log of all references to the session
]SetDefaultProject Specifies the project to be used in case no project is specified
]Squash Squashes some commits; The user will be questioned which ones
]Status Reports all untracked files and/or all uncommitted changes
]Version APLGit2's version: returns name, version number & version date
Note that CurrentBranch
is available as an API function but not as a user command. This is because internally it is often needed, but there is hardly any need for a user command, in particular because the command ]ListBranches
and ]Status
both report the current branch anyway.