README
¶
goutils/v2/git
The git package is a collection of utility functions
designed to simplify common git tasks.
Table of contents
Functions
AddFile(string)
AddFile(string) error
AddFile adds the file located at the given file path to its affiliated Git repository. An error is returned if an issue happens during this process.
Parameters:
filePath: A string indicating the path to the file that will be staged.
Returns:
error: An error if any occurs during the staging process.
CloneRepo(string, string, transport.AuthMethod)
CloneRepo(string, string, transport.AuthMethod) *git.Repository, error
CloneRepo clones a Git repository from the specified URL to the given path, using the supplied authentication method, if provided.
Parameters:
url: A string indicating the URL of the repository to clone. clonePath: A string representing the path where the repository will be cloned. auth: A transport.AuthMethod interface symbolizing the authentication method for cloning. If nil, no authentication is used.
Returns:
*git.Repository: A pointer to the Repository struct representing the cloned repository.
error: An error if the repository can't be cloned or already exists at the target path.
Commit(*git.Repository, string)
Commit(*git.Repository, string) error
Commit generates a new commit in the specified repository with the given message. The commit's author is extracted from the global Git user settings.
Parameters:
repo: A pointer to the Repository struct symbolizing the repository where the commit should be made. msg: A string depicting the commit message.
Returns:
error: An error if the commit can't be created.
CreateTag(*git.Repository, string)
CreateTag(*git.Repository, string) error
CreateTag forms a new tag in the specified repository.
Parameters:
repo: Pointer to the Repository struct, the repository where the tag is created. tag: String, the name of the tag to create.
Returns:
error: Error if the tag can't be created, already exists, or if the global git user settings can't be retrieved.
DeletePushedTag(*git.Repository, string, transport.AuthMethod)
DeletePushedTag(*git.Repository, string, transport.AuthMethod) error
DeletePushedTag deletes a tag from a repository that has been pushed.
Parameters:
repo: Repository where the tag should be deleted. tag: The tag that should be deleted. auth: Authentication method for the push.
Returns:
error: Error if the tag cannot be deleted.
DeleteTag(*git.Repository, string)
DeleteTag(*git.Repository, string) error
DeleteTag deletes the local input tag from the specified repo.
Parameters:
repo: Repository where the tag should be deleted. tag: The tag that should be deleted.
Returns:
error: Error if the tag cannot be deleted.
GetGlobalUserCfg()
GetGlobalUserCfg() ConfigUserInfo, error
GetGlobalUserCfg fetches the username and email from the global git user settings. It returns a ConfigUserInfo struct containing the global git username and email. An error is returned if the global git username or email cannot be retrieved.
Returns:
ConfigUserInfo: Struct containing the global git username and email.
error: Error if the global git username or email can't be retrieved.
GetTags(*git.Repository)
GetTags(*git.Repository) []string, error
GetTags returns all tags of the given repository.
Parameters:
repo: A pointer to the Repository struct representing the repo from which tags are retrieved.
Returns:
[]string: A slice of strings, each representing a tag in the repository. error: An error if a problem occurs while retrieving the tags.
PullRepos(...string)
PullRepos(...string) error
PullRepos updates all git repositories located in the specified directories.
Parameters:
dirs: Paths to directories to be searched for git repositories.
Returns:
error: Error if there's a problem with pulling the repositories.
Push(*git.Repository, transport.AuthMethod)
Push(*git.Repository, transport.AuthMethod) error
Push transmits the contents of the specified repository to the default remote (origin).
Parameters:
repo: Pointer to the Repository struct, the repository to push. auth: A transport.AuthMethod interface, the authentication method for the push. If it's nil, no authentication is used.
Returns:
error: Error if the push fails.
PushTag(*git.Repository, string, transport.AuthMethod)
PushTag(*git.Repository, string, transport.AuthMethod) error
PushTag pushes a specific tag of the given repository to the default remote.
Parameters:
repo: Repository where the tag should be pushed. tag: Name of the tag to push. auth: Authentication method for the push. If nil, no authentication is used.
Returns:
error: Error if the push fails.
RepoRoot()
RepoRoot() string, error
RepoRoot finds and returns the root directory of the current Git repository.
Returns:
string: Absolute path to the root directory of the current Git repository. error: Error if the Git repository root cannot be found.
Installation
To use the goutils/v2/git package, you first need to install it. Follow the steps below to install via go get.
go get github.com/l50/goutils/v2/git
Usage
After installation, you can import the package in your Go project using the following import statement:
import "github.com/l50/goutils/v2/git"
Tests
To ensure the package is working correctly, run the following
command to execute the tests for goutils/v2/git:
go test -v
Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Documentation
¶
Index ¶
- func AddFile(filePath string) error
- func CloneRepo(url string, clonePath string, auth transport.AuthMethod) (*git.Repository, error)
- func Commit(repo *git.Repository, msg string) error
- func CreateTag(repo *git.Repository, tag string) error
- func DeletePushedTag(repo *git.Repository, tag string, auth transport.AuthMethod) error
- func DeleteTag(repo *git.Repository, tag string) error
- func GetTags(repo *git.Repository) ([]string, error)
- func PullRepos(dirs ...string) error
- func Push(repo *git.Repository, auth transport.AuthMethod) error
- func PushTag(repo *git.Repository, tag string, auth transport.AuthMethod) error
- func RepoRoot() (string, error)
- type ConfigUserInfo
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddFile ¶
AddFile adds the file located at the given file path to its affiliated Git repository. An error is returned if an issue happens during this process.
**Parameters:**
filePath: A string indicating the path to the file that will be staged.
**Returns:**
error: An error if any occurs during the staging process.
Example ¶
package main
import (
"log"
gitutils "github.com/l50/goutils/v2/git"
)
func main() {
filePath := "/path/to/your/dummy/file"
if err := gitutils.AddFile(filePath); err != nil {
log.Fatalf("failed to stage file: %v", err)
}
log.Printf("Staged file: %s", filePath)
}
Output:
func CloneRepo ¶
func CloneRepo(url string, clonePath string, auth transport.AuthMethod) ( *git.Repository, error)
CloneRepo clones a Git repository from the specified URL to the given path, using the supplied authentication method, if provided.
**Parameters:**
url: A string indicating the URL of the repository to clone. clonePath: A string representing the path where the repository will be cloned. auth: A transport.AuthMethod interface symbolizing the authentication method for cloning. If nil, no authentication is used.
**Returns:**
*git.Repository: A pointer to the Repository struct representing the cloned repository.
error: An error if the repository can't be cloned or already exists at the target path.
Example ¶
package main
import (
"log"
"github.com/go-git/go-git/v5/plumbing/transport/http"
gitutils "github.com/l50/goutils/v2/git"
)
func main() {
url := "https://github.com/dummy/repo.git"
clonePath := "/path/to/dummy/repo"
auth := &http.BasicAuth{
Username: "dummy_username",
Password: "dummy_password",
}
_, err := gitutils.CloneRepo(url, clonePath, auth)
if err != nil {
log.Fatalf("failed to clone repository: %v", err)
}
}
Output:
func Commit ¶
Commit generates a new commit in the specified repository with the given message. The commit's author is extracted from the global Git user settings.
**Parameters:**
repo: A pointer to the Repository struct symbolizing the repository where the commit should be made. msg: A string depicting the commit message.
**Returns:**
error: An error if the commit can't be created.
Example ¶
repo, _ := git.PlainOpen("/path/to/dummy/repo")
msg := "Dummy commit message"
if err := gitutils.Commit(repo, msg); err != nil {
log.Fatalf("failed to create commit: %v", err)
}
Output:
func CreateTag ¶
CreateTag forms a new tag in the specified repository.
**Parameters:**
repo: Pointer to the Repository struct, the repository where the tag is created. tag: String, the name of the tag to create.
**Returns:**
error: Error if the tag can't be created, already exists, or if the global git user settings can't be retrieved.
Example ¶
ExampleCreateTag demonstrates usage of CreateTag function.
repo, err := git.PlainOpen("/path/to/repo")
if err != nil {
log.Fatalf("failed to open repository: %v", err)
}
tag := "v1.0.0"
if err := gitutils.CreateTag(repo, tag); err != nil {
log.Fatalf("failed to create tag: %v", err)
}
Output:
func DeletePushedTag ¶
func DeletePushedTag(repo *git.Repository, tag string, auth transport.AuthMethod) error
DeletePushedTag deletes a tag from a repository that has been pushed.
**Parameters:**
repo: Repository where the tag should be deleted. tag: The tag that should be deleted. auth: Authentication method for the push.
**Returns:**
error: Error if the tag cannot be deleted.
func DeleteTag ¶
DeleteTag deletes the local input tag from the specified repo.
**Parameters:**
repo: Repository where the tag should be deleted. tag: The tag that should be deleted.
**Returns:**
error: Error if the tag cannot be deleted.
Example ¶
ExampleDeleteTag demonstrates usage of DeleteTag function.
_, err := git.PlainOpen("/path/to/repo")
if err != nil {
log.Fatalf("failed to open repository: %v", err)
}
Output:
func GetTags ¶
GetTags returns all tags of the given repository.
**Parameters:**
repo: A pointer to the Repository struct representing the repo from which tags are retrieved.
**Returns:**
[]string: A slice of strings, each representing a tag in the repository. error: An error if a problem occurs while retrieving the tags.
Example ¶
ExampleGetTags demonstrates usage of GetTags function.
repo, err := git.PlainOpen("/path/to/repo")
if err != nil {
log.Fatalf("failed to open repository: %v", err)
}
_, err = gitutils.GetTags(repo)
if err != nil {
log.Fatalf("failed to get tags: %v", err)
}
Output:
func PullRepos ¶
PullRepos updates all git repositories located in the specified directories.
**Parameters:**
dirs: Paths to directories to be searched for git repositories.
**Returns:**
error: Error if there's a problem with pulling the repositories.
Example ¶
ExamplePullRepos demonstrates usage of PullRepos function.
package main
import (
"log"
gitutils "github.com/l50/goutils/v2/git"
)
func main() {
dirs := []string{"/path/to/your/directory", "/another/path/to/your/directory"}
if err := gitutils.PullRepos(dirs...); err != nil {
log.Fatalf("failed to pull repos: %v", err)
}
}
Output:
func Push ¶
func Push(repo *git.Repository, auth transport.AuthMethod) error
Push transmits the contents of the specified repository to the default remote (origin).
**Parameters:**
repo: Pointer to the Repository struct, the repository to push. auth: A transport.AuthMethod interface, the authentication method for the push. If it's nil, no authentication is used.
**Returns:**
error: Error if the push fails.
Example ¶
ExamplePush demonstrates usage of Push function.
repo, err := git.PlainOpen("/path/to/repo")
if err != nil {
log.Fatalf("failed to open repository: %v", err)
}
auth := &http.BasicAuth{
Username: "your_username",
Password: "your_password",
}
if err := gitutils.Push(repo, auth); err != nil {
log.Fatalf("failed to push to remote: %v", err)
}
Output:
func PushTag ¶
func PushTag(repo *git.Repository, tag string, auth transport.AuthMethod) error
PushTag pushes a specific tag of the given repository to the default remote.
**Parameters:**
repo: Repository where the tag should be pushed. tag: Name of the tag to push. auth: Authentication method for the push. If nil, no authentication is used.
**Returns:**
error: Error if the push fails.
Example ¶
ExamplePushTag demonstrates usage of PushTag function.
repo, err := git.PlainOpen("/path/to/repo")
if err != nil {
log.Fatalf("failed to open repository: %v", err)
}
tag := "v1.0.0"
auth := &http.BasicAuth{
Username: "your_username",
Password: "your_password",
}
if err := gitutils.PushTag(repo, tag, auth); err != nil {
log.Fatalf("failed to push tag: %v", err)
}
Output:
func RepoRoot ¶
RepoRoot finds and returns the root directory of the current Git repository.
**Returns:**
string: Absolute path to the root directory of the current Git repository. error: Error if the Git repository root cannot be found.
Example ¶
ExampleRepoRoot demonstrates usage of RepoRoot function.
package main
import (
"fmt"
"log"
gitutils "github.com/l50/goutils/v2/git"
)
func main() {
root, err := gitutils.RepoRoot()
if err != nil {
log.Fatalf("failed to retrieve root: %v", err)
}
fmt.Printf("The root of the current Git repository is: %s\n", root)
}
Output:
Types ¶
type ConfigUserInfo ¶
ConfigUserInfo holds user details for the git configuration.
**Attributes:**
User: Global git username. Email: Email associated with the global git user.
func GetGlobalUserCfg ¶
func GetGlobalUserCfg() (ConfigUserInfo, error)
GetGlobalUserCfg fetches the username and email from the global git user settings. It returns a ConfigUserInfo struct containing the global git username and email. An error is returned if the global git username or email cannot be retrieved.
**Returns:**
ConfigUserInfo: Struct containing the global git username and email.
error: Error if the global git username or email can't be retrieved.
Example ¶
ExampleGetGlobalUserCfg demonstrates usage of GetGlobalUserCfg function.
package main
import (
"log"
gitutils "github.com/l50/goutils/v2/git"
)
func main() {
_, err := gitutils.GetGlobalUserCfg()
if err != nil {
log.Fatalf("failed to retrieve global git user settings: %v", err)
}
}
Output:
Source Files