There are two approaches the plugin uses to identify the current branch:
- Read from an external
.what-git-branch
file - Read data in the
.git
directory
The first approach looks for .what-git-branch
(defined in Repository::EXTERNAL_FILE
) file in the searchable paths, and if found, uses the file's contents as the current head reference.
If this file is not found, the second approach is used.
The second and final approach reads the .git/HEAD
file, and parses it for the checked out branch's name.
The plugin by default checks ABSPATH
and WP_CONTENT_DIR
directories for a .git
directory, or a .what-git-branch
file.
More paths can be added via the what-git-branch/get_dirs_from_scan()/$addtl_paths
filter.
To display the branch deployed to a remote environment (a.k.a. an environment without a git repository, or with a different git repository), write the branch name to the .what-git-branch
file in one of the searchable path directories.
The following git command will return the currently checked out branch:
git rev-parse --abbrev-ref HEAD
In a GitHub Action, this may look similar to this (depending on your deploy process and directory structure):
jobs:
job-name:
steps:
- run: echo ${GITUHB_REF#refs/heads/} > .what-git-branch
Set the directory for the primary repository. The primary repository will be highlighted in the Dashboard widget, and is displayed in the admin bar.
Hard-code the directories with repositories to improve performance by preventing filesystem scanning.
add_filter( 'what-git-branch/get_dirs_from_filter()/$dirs', static function ( array $dirs ) : array {
$dirs = array(
ABSPATH,
WP_PLUGIN_DIR . '/what-git-branch',
);
} );
Additional paths outside of WP_CONTENT_DIR
to scan for repositories.
Identifying key for context to perform directory scan. Function \What_Git_Branch\Plugin::when_can_scan()
will output one of the following:
never
http-request
manually
cli
heartbeat
Change directories caching store between options and transients.
Expected values:
option
transient
Expiration of transient for directories cache.
Skip printing repository(ies) in Dashboard widget.
Set name of repository; defaults to repository's directory's name.
Filter the reference for HEAD
for repository.
Change branch name for repository.
Add link to repository on GitHub by setting user and repository name: user/repository
.
add_filter( 'what-git-branch/get_github_url()/$github_repo', static function ( $github_repo, $path ) {
if ( false === stripos( $path, 'what-git-branch' ) ) {
return $github_repo;
}
return 'crstauf/what-git-branch';
}, 10, 2 );
List the repositories, directories, and head refs.
If permitted, scan the filesystem for repositories.
Clear the directories cache.
Print the head ref of the primary repository.
Print the path of the primary repository.
Set head ref of primary repository to $text
.
Reset head ref of primary repository (remove external file and use git data).