Coverage for tsfpga/git_utils.py: 93%

1# -------------------------------------------------------------------------------------------------- 

2# Copyright (c) Lukas Vik. All rights reserved. 

3# 

4# This file is part of the tsfpga project, a project platform for modern FPGA development. 

5# https://tsfpga.com 

6# https://github.com/tsfpga/tsfpga 

7# -------------------------------------------------------------------------------------------------- 

8 

9from __future__ import annotations 

10 

11import os 

12from pathlib import Path 

13from typing import TYPE_CHECKING 

14 

15from tsfpga.system_utils import file_is_in_directory 

16 

17if TYPE_CHECKING: 

18 from collections.abc import Iterator 

19 

20 from git.objects.tree import Tree 

21 

22 

23def get_git_commit(directory: Path, use_rst_annotation: bool = False) -> str: 

24 """ 

25 Get a string describing the current git commit. 

26 E.g. ``"abcdef0123"`` or ``"12345678 (local changes present)"``. 

27 

28 Arguments: 

29 directory: The directory where git commands will be run. 

30 use_rst_annotation: Use reStructuredText literal annotation for the SHA value. 

31 

32 Return: 

33 Git commit information. 

34 """ 

35 annotation = "``" if use_rst_annotation else "" 

36 git_sha = get_git_sha(directory=directory) 

37 result = f"{annotation}{git_sha}{annotation}" 

38 

39 if git_local_changes_present(directory=directory): 

40 result += " (local changes present)" 

41 

42 return result 

43 

44 

45def get_git_sha(directory: Path) -> str: 

46 """ 

47 Get a short git SHA. 

48 

49 Arguments: 

50 directory: The directory where git commands will be run. 

51 

52 Return: 

53 The SHA. 

54 """ 

55 # Generally, eight to ten characters are more than enough to be unique within a project. 

56 # The linux kernel, one of the largest projects, needs 12. 

57 # https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection#Short-SHA-1 

58 sha_length = 12 

59 

60 if "GIT_COMMIT" in os.environ: 

61 return os.environ["GIT_COMMIT"][0:sha_length] 

62 

63 # Import fails if "git" executable is not available, hence it can not be on top level. 

64 # This function should only be called if git is available. 

65 

66 from git.repo import Repo 

67 

68 repo = Repo(directory, search_parent_directories=True) 

69 return repo.head.commit.hexsha[0:sha_length] 

70 

71 

72def git_local_changes_present(directory: Path) -> bool: 

73 """ 

74 Check if the git repo has local changes. 

75 

76 Arguments: 

77 directory: The directory where git commands will be run. 

78 

79 Return: 

80 ``True`` if the repo contains changes that have been made after the last commit. 

81 """ 

82 # Import fails if "git" executable is not available, hence it can not be on top level. 

83 # This function should only be called if git is available. 

84 

85 from git.repo import Repo 

86 

87 repo = Repo(directory, search_parent_directories=True) 

88 

89 return repo.is_dirty() 

90 

91 

92def git_commands_are_available(directory: Path) -> bool: 

93 """ 

94 True if "git" command executable is available, and ``directory`` is in a valid git repo. 

95 """ 

96 try: 

97 from git import InvalidGitRepositoryError 

98 from git.repo import Repo 

99 except ImportError: 

100 return False 

101 

102 try: 

103 Repo(directory, search_parent_directories=True) 

104 except InvalidGitRepositoryError: 

105 return False 

106 

107 return True 

108 

109 

110def find_git_files( 

111 directory: Path, 

112 exclude_directories: list[Path] | None = None, 

113 file_endings_include: str | tuple[str] | None = None, 

114 file_endings_avoid: str | tuple[str] | None = None, 

115) -> Iterator[Path]: 

116 """ 

117 Find files that are checked in to git. 

118 

119 Arguments: 

120 directory: Search in this directory. 

121 exclude_directories: Files in these directories will not be included. 

122 file_endings_include: Only files with these endings will be included. 

123 file_endings_avoid: Files with these endings will not be included. 

124 

125 Return: 

126 The files that are available in git. 

127 """ 

128 # Import fails if "git" executable is not available, hence it can not be on top level. 

129 # This function should only be called if git is available. 

130 

131 from git.repo import Repo 

132 

133 exclude_directories = ( 

134 [] 

135 if exclude_directories is None 

136 else [exclude_directory.resolve() for exclude_directory in exclude_directories] 

137 ) 

138 

139 def list_paths(root_tree: Tree, path: Path) -> Iterator[Path]: 

140 for blob in root_tree.blobs: 

141 yield path / blob.name 

142 for tree in root_tree.trees: 

143 yield from list_paths(tree, path / tree.name) 

144 

145 repo = Repo(directory, search_parent_directories=True) 

146 repo_root = Path(repo.working_dir).resolve() 

147 

148 for file_path in list_paths(root_tree=repo.tree(), path=repo_root): 

149 if file_endings_include is not None and not file_path.name.endswith(file_endings_include): 

150 continue 

151 

152 if file_endings_avoid is not None and file_path.name.endswith(file_endings_avoid): 

153 continue 

154 

155 if file_is_in_directory(file_path, exclude_directories): 

156 continue 

157 

158 if file_is_in_directory(file_path, [directory]): 

159 yield file_path