1 # SPDX-License-Identifier: GPL-2.0+
2 # Copyright (c) 2011 The Chromium OS Authors.
10 from patman import command
11 from patman import settings
12 from patman import terminal
13 from patman import tools
15 # True to use --no-decorate - we check this in Setup()
16 use_no_decorate = True
18 def LogCmd(commit_range, git_dir=None, oneline=False, reverse=False,
20 """Create a command to perform a 'git log'
23 commit_range: Range expression to use for log, None for none
24 git_dir: Path to git repository (None to use default)
25 oneline: True to use --oneline, else False
26 reverse: True to reverse the log (--reverse)
27 count: Number of commits to list, or None for no limit
29 List containing command and arguments to run
33 cmd += ['--git-dir', git_dir]
34 cmd += ['--no-pager', 'log', '--no-color']
36 cmd.append('--oneline')
38 cmd.append('--no-decorate')
40 cmd.append('--reverse')
42 cmd.append('-n%d' % count)
44 cmd.append(commit_range)
46 # Add this in case we have a branch with the same name as a directory.
47 # This avoids messages like this, for example:
48 # fatal: ambiguous argument 'test': both revision and filename
52 def CountCommitsToBranch(branch):
53 """Returns number of commits between HEAD and the tracking branch.
55 This looks back to the tracking branch and works out the number of commits
59 branch: Branch to count from (None for current branch)
62 Number of patches that exist on top of the branch
65 us, msg = GetUpstream('.git', branch)
66 rev_range = '%s..%s' % (us, branch)
68 rev_range = '@{upstream}..'
69 pipe = [LogCmd(rev_range, oneline=True)]
70 result = command.RunPipe(pipe, capture=True, capture_stderr=True,
71 oneline=True, raise_on_error=False)
72 if result.return_code:
73 raise ValueError('Failed to determine upstream: %s' %
74 result.stderr.strip())
75 patch_count = len(result.stdout.splitlines())
78 def NameRevision(commit_hash):
79 """Gets the revision name for a commit
82 commit_hash: Commit hash to look up
85 Name of revision, if any, else None
87 pipe = ['git', 'name-rev', commit_hash]
88 stdout = command.RunPipe([pipe], capture=True, oneline=True).stdout
90 # We expect a commit, a space, then a revision name
91 name = stdout.split(' ')[1].strip()
94 def GuessUpstream(git_dir, branch):
95 """Tries to guess the upstream for a branch
97 This lists out top commits on a branch and tries to find a suitable
98 upstream. It does this by looking for the first commit where
99 'git name-rev' returns a plain branch name, with no ! or ^ modifiers.
102 git_dir: Git directory containing repo
103 branch: Name of branch
107 Name of upstream branch (e.g. 'upstream/master') or None if none
108 Warning/error message, or None if none
110 pipe = [LogCmd(branch, git_dir=git_dir, oneline=True, count=100)]
111 result = command.RunPipe(pipe, capture=True, capture_stderr=True,
112 raise_on_error=False)
113 if result.return_code:
114 return None, "Branch '%s' not found" % branch
115 for line in result.stdout.splitlines()[1:]:
116 commit_hash = line.split(' ')[0]
117 name = NameRevision(commit_hash)
118 if '~' not in name and '^' not in name:
119 if name.startswith('remotes/'):
121 return name, "Guessing upstream as '%s'" % name
122 return None, "Cannot find a suitable upstream for branch '%s'" % branch
124 def GetUpstream(git_dir, branch):
125 """Returns the name of the upstream for a branch
128 git_dir: Git directory containing repo
129 branch: Name of branch
133 Name of upstream branch (e.g. 'upstream/master') or None if none
134 Warning/error message, or None if none
137 remote = command.OutputOneLine('git', '--git-dir', git_dir, 'config',
138 'branch.%s.remote' % branch)
139 merge = command.OutputOneLine('git', '--git-dir', git_dir, 'config',
140 'branch.%s.merge' % branch)
142 upstream, msg = GuessUpstream(git_dir, branch)
147 elif remote and merge:
148 leaf = merge.split('/')[-1]
149 return '%s/%s' % (remote, leaf), None
151 raise ValueError("Cannot determine upstream branch for branch "
152 "'%s' remote='%s', merge='%s'" % (branch, remote, merge))
155 def GetRangeInBranch(git_dir, branch, include_upstream=False):
156 """Returns an expression for the commits in the given branch.
159 git_dir: Directory containing git repo
160 branch: Name of branch
162 Expression in the form 'upstream..branch' which can be used to
163 access the commits. If the branch does not exist, returns None.
165 upstream, msg = GetUpstream(git_dir, branch)
168 rstr = '%s%s..%s' % (upstream, '~' if include_upstream else '', branch)
171 def CountCommitsInRange(git_dir, range_expr):
172 """Returns the number of commits in the given range.
175 git_dir: Directory containing git repo
176 range_expr: Range to check
178 Number of patches that exist in the supplied range or None if none
181 pipe = [LogCmd(range_expr, git_dir=git_dir, oneline=True)]
182 result = command.RunPipe(pipe, capture=True, capture_stderr=True,
183 raise_on_error=False)
184 if result.return_code:
185 return None, "Range '%s' not found or is invalid" % range_expr
186 patch_count = len(result.stdout.splitlines())
187 return patch_count, None
189 def CountCommitsInBranch(git_dir, branch, include_upstream=False):
190 """Returns the number of commits in the given branch.
193 git_dir: Directory containing git repo
194 branch: Name of branch
196 Number of patches that exist on top of the branch, or None if the
197 branch does not exist.
199 range_expr, msg = GetRangeInBranch(git_dir, branch, include_upstream)
202 return CountCommitsInRange(git_dir, range_expr)
204 def CountCommits(commit_range):
205 """Returns the number of commits in the given range.
208 commit_range: Range of commits to count (e.g. 'HEAD..base')
210 Number of patches that exist on top of the branch
212 pipe = [LogCmd(commit_range, oneline=True),
214 stdout = command.RunPipe(pipe, capture=True, oneline=True).stdout
215 patch_count = int(stdout)
218 def Checkout(commit_hash, git_dir=None, work_tree=None, force=False):
219 """Checkout the selected commit for this build
222 commit_hash: Commit hash to check out
226 pipe.extend(['--git-dir', git_dir])
228 pipe.extend(['--work-tree', work_tree])
229 pipe.append('checkout')
232 pipe.append(commit_hash)
233 result = command.RunPipe([pipe], capture=True, raise_on_error=False,
235 if result.return_code != 0:
236 raise OSError('git checkout (%s): %s' % (pipe, result.stderr))
238 def Clone(git_dir, output_dir):
239 """Checkout the selected commit for this build
242 commit_hash: Commit hash to check out
244 pipe = ['git', 'clone', git_dir, '.']
245 result = command.RunPipe([pipe], capture=True, cwd=output_dir,
247 if result.return_code != 0:
248 raise OSError('git clone: %s' % result.stderr)
250 def Fetch(git_dir=None, work_tree=None):
251 """Fetch from the origin repo
254 commit_hash: Commit hash to check out
258 pipe.extend(['--git-dir', git_dir])
260 pipe.extend(['--work-tree', work_tree])
262 result = command.RunPipe([pipe], capture=True, capture_stderr=True)
263 if result.return_code != 0:
264 raise OSError('git fetch: %s' % result.stderr)
266 def CheckWorktreeIsAvailable(git_dir):
267 """Check if git-worktree functionality is available
270 git_dir: The repository to test in
273 True if git-worktree commands will work, False otherwise.
275 pipe = ['git', '--git-dir', git_dir, 'worktree', 'list']
276 result = command.RunPipe([pipe], capture=True, capture_stderr=True,
277 raise_on_error=False)
278 return result.return_code == 0
280 def AddWorktree(git_dir, output_dir, commit_hash=None):
281 """Create and checkout a new git worktree for this build
284 git_dir: The repository to checkout the worktree from
285 output_dir: Path for the new worktree
286 commit_hash: Commit hash to checkout
288 # We need to pass --detach to avoid creating a new branch
289 pipe = ['git', '--git-dir', git_dir, 'worktree', 'add', '.', '--detach']
291 pipe.append(commit_hash)
292 result = command.RunPipe([pipe], capture=True, cwd=output_dir,
294 if result.return_code != 0:
295 raise OSError('git worktree add: %s' % result.stderr)
297 def PruneWorktrees(git_dir):
298 """Remove administrative files for deleted worktrees
301 git_dir: The repository whose deleted worktrees should be pruned
303 pipe = ['git', '--git-dir', git_dir, 'worktree', 'prune']
304 result = command.RunPipe([pipe], capture=True, capture_stderr=True)
305 if result.return_code != 0:
306 raise OSError('git worktree prune: %s' % result.stderr)
308 def CreatePatches(branch, start, count, ignore_binary, series):
309 """Create a series of patches from the top of the current branch.
311 The patch files are written to the current directory using
315 branch: Branch to create patches from (None for current branch)
316 start: Commit to start from: 0=HEAD, 1=next one, etc.
317 count: number of commits to include
318 ignore_binary: Don't generate patches for binary files
319 series: Series object for this series (set of patches)
321 Filename of cover letter (None if none)
322 List of filenames of patch files
324 if series.get('version'):
325 version = '%s ' % series['version']
326 cmd = ['git', 'format-patch', '-M', '--signoff']
328 cmd.append('--no-binary')
329 if series.get('cover'):
330 cmd.append('--cover-letter')
331 prefix = series.GetPatchPrefix()
333 cmd += ['--subject-prefix=%s' % prefix]
334 brname = branch or 'HEAD'
335 cmd += ['%s~%d..%s~%d' % (brname, start + count, brname, start)]
337 stdout = command.RunList(cmd)
338 files = stdout.splitlines()
340 # We have an extra file if there is a cover letter
341 if series.get('cover'):
342 return files[0], files[1:]
346 def BuildEmailList(in_list, tag=None, alias=None, raise_on_error=True):
347 """Build a list of email addresses based on an input list.
349 Takes a list of email addresses and aliases, and turns this into a list
350 of only email address, by resolving any aliases that are present.
352 If the tag is given, then each email address is prepended with this
353 tag and a space. If the tag starts with a minus sign (indicating a
354 command line parameter) then the email address is quoted.
357 in_list: List of aliases/email addresses
358 tag: Text to put before each address
359 alias: Alias dictionary
360 raise_on_error: True to raise an error when an alias fails to match,
361 False to just print a message.
364 List of email addresses
367 >>> alias['fred'] = ['f.bloggs@napier.co.nz']
368 >>> alias['john'] = ['j.bloggs@napier.co.nz']
369 >>> alias['mary'] = ['Mary Poppins <m.poppins@cloud.net>']
370 >>> alias['boys'] = ['fred', ' john']
371 >>> alias['all'] = ['fred ', 'john', ' mary ']
372 >>> BuildEmailList(['john', 'mary'], None, alias)
373 ['j.bloggs@napier.co.nz', 'Mary Poppins <m.poppins@cloud.net>']
374 >>> BuildEmailList(['john', 'mary'], '--to', alias)
375 ['--to "j.bloggs@napier.co.nz"', \
376 '--to "Mary Poppins <m.poppins@cloud.net>"']
377 >>> BuildEmailList(['john', 'mary'], 'Cc', alias)
378 ['Cc j.bloggs@napier.co.nz', 'Cc Mary Poppins <m.poppins@cloud.net>']
380 quote = '"' if tag and tag[0] == '-' else ''
383 raw += LookupEmail(item, alias, raise_on_error=raise_on_error)
386 item = tools.FromUnicode(item)
387 if not item in result:
390 return ['%s %s%s%s' % (tag, quote, email, quote) for email in result]
393 def CheckSuppressCCConfig():
394 """Check if sendemail.suppresscc is configured correctly.
397 True if the option is configured correctly, False otherwise.
399 suppresscc = command.OutputOneLine('git', 'config', 'sendemail.suppresscc',
400 raise_on_error=False)
402 # Other settings should be fine.
403 if suppresscc == 'all' or suppresscc == 'cccmd':
404 col = terminal.Color()
406 print((col.Color(col.RED, "error") +
407 ": git config sendemail.suppresscc set to %s\n" % (suppresscc)) +
408 " patman needs --cc-cmd to be run to set the cc list.\n" +
410 " git config --unset sendemail.suppresscc\n" +
411 " Or read the man page:\n" +
412 " git send-email --help\n" +
413 " and set an option that runs --cc-cmd\n")
418 def EmailPatches(series, cover_fname, args, dry_run, raise_on_error, cc_fname,
419 self_only=False, alias=None, in_reply_to=None, thread=False,
421 """Email a patch series.
424 series: Series object containing destination info
425 cover_fname: filename of cover letter
426 args: list of filenames of patch files
427 dry_run: Just return the command that would be run
428 raise_on_error: True to raise an error when an alias fails to match,
429 False to just print a message.
430 cc_fname: Filename of Cc file for per-commit Cc
431 self_only: True to just email to yourself as a test
432 in_reply_to: If set we'll pass this to git as --in-reply-to.
433 Should be a message ID that this is in reply to.
434 thread: True to add --thread to git send-email (make
435 all patches reply to cover-letter or first patch in series)
436 smtp_server: SMTP server to use to send patches
439 Git command that was/would be run
441 # For the duration of this doctest pretend that we ran patman with ./patman
442 >>> _old_argv0 = sys.argv[0]
443 >>> sys.argv[0] = './patman'
446 >>> alias['fred'] = ['f.bloggs@napier.co.nz']
447 >>> alias['john'] = ['j.bloggs@napier.co.nz']
448 >>> alias['mary'] = ['m.poppins@cloud.net']
449 >>> alias['boys'] = ['fred', ' john']
450 >>> alias['all'] = ['fred ', 'john', ' mary ']
451 >>> alias[os.getenv('USER')] = ['this-is-me@me.com']
453 >>> series['to'] = ['fred']
454 >>> series['cc'] = ['mary']
455 >>> EmailPatches(series, 'cover', ['p1', 'p2'], True, True, 'cc-fname', \
457 'git send-email --annotate --to "f.bloggs@napier.co.nz" --cc \
458 "m.poppins@cloud.net" --cc-cmd "./patman --cc-cmd cc-fname" cover p1 p2'
459 >>> EmailPatches(series, None, ['p1'], True, True, 'cc-fname', False, \
461 'git send-email --annotate --to "f.bloggs@napier.co.nz" --cc \
462 "m.poppins@cloud.net" --cc-cmd "./patman --cc-cmd cc-fname" p1'
463 >>> series['cc'] = ['all']
464 >>> EmailPatches(series, 'cover', ['p1', 'p2'], True, True, 'cc-fname', \
466 'git send-email --annotate --to "this-is-me@me.com" --cc-cmd "./patman \
467 --cc-cmd cc-fname" cover p1 p2'
468 >>> EmailPatches(series, 'cover', ['p1', 'p2'], True, True, 'cc-fname', \
470 'git send-email --annotate --to "f.bloggs@napier.co.nz" --cc \
471 "f.bloggs@napier.co.nz" --cc "j.bloggs@napier.co.nz" --cc \
472 "m.poppins@cloud.net" --cc-cmd "./patman --cc-cmd cc-fname" cover p1 p2'
474 # Restore argv[0] since we clobbered it.
475 >>> sys.argv[0] = _old_argv0
477 to = BuildEmailList(series.get('to'), '--to', alias, raise_on_error)
479 git_config_to = command.Output('git', 'config', 'sendemail.to',
480 raise_on_error=False)
481 if not git_config_to:
482 print("No recipient.\n"
483 "Please add something like this to a commit\n"
484 "Series-to: Fred Bloggs <f.blogs@napier.co.nz>\n"
485 "Or do something like this\n"
486 "git config sendemail.to u-boot@lists.denx.de")
488 cc = BuildEmailList(list(set(series.get('cc')) - set(series.get('to'))),
489 '--cc', alias, raise_on_error)
491 to = BuildEmailList([os.getenv('USER')], '--to', alias, raise_on_error)
493 cmd = ['git', 'send-email', '--annotate']
495 cmd.append('--smtp-server=%s' % smtp_server)
497 cmd.append('--in-reply-to="%s"' % tools.FromUnicode(in_reply_to))
499 cmd.append('--thread')
503 cmd += ['--cc-cmd', '"%s --cc-cmd %s"' % (sys.argv[0], cc_fname)]
505 cmd.append(cover_fname)
507 cmdstr = ' '.join(cmd)
513 def LookupEmail(lookup_name, alias=None, raise_on_error=True, level=0):
514 """If an email address is an alias, look it up and return the full name
516 TODO: Why not just use git's own alias feature?
519 lookup_name: Alias or email address to look up
520 alias: Dictionary containing aliases (None to use settings default)
521 raise_on_error: True to raise an error when an alias fails to match,
522 False to just print a message.
526 list containing a list of email addresses
529 OSError if a recursive alias reference was found
530 ValueError if an alias was not found
533 >>> alias['fred'] = ['f.bloggs@napier.co.nz']
534 >>> alias['john'] = ['j.bloggs@napier.co.nz']
535 >>> alias['mary'] = ['m.poppins@cloud.net']
536 >>> alias['boys'] = ['fred', ' john', 'f.bloggs@napier.co.nz']
537 >>> alias['all'] = ['fred ', 'john', ' mary ']
538 >>> alias['loop'] = ['other', 'john', ' mary ']
539 >>> alias['other'] = ['loop', 'john', ' mary ']
540 >>> LookupEmail('mary', alias)
541 ['m.poppins@cloud.net']
542 >>> LookupEmail('arthur.wellesley@howe.ro.uk', alias)
543 ['arthur.wellesley@howe.ro.uk']
544 >>> LookupEmail('boys', alias)
545 ['f.bloggs@napier.co.nz', 'j.bloggs@napier.co.nz']
546 >>> LookupEmail('all', alias)
547 ['f.bloggs@napier.co.nz', 'j.bloggs@napier.co.nz', 'm.poppins@cloud.net']
548 >>> LookupEmail('odd', alias)
549 Traceback (most recent call last):
551 ValueError: Alias 'odd' not found
552 >>> LookupEmail('loop', alias)
553 Traceback (most recent call last):
555 OSError: Recursive email alias at 'other'
556 >>> LookupEmail('odd', alias, raise_on_error=False)
557 Alias 'odd' not found
559 >>> # In this case the loop part will effectively be ignored.
560 >>> LookupEmail('loop', alias, raise_on_error=False)
561 Recursive email alias at 'other'
562 Recursive email alias at 'john'
563 Recursive email alias at 'mary'
564 ['j.bloggs@napier.co.nz', 'm.poppins@cloud.net']
567 alias = settings.alias
568 lookup_name = lookup_name.strip()
569 if '@' in lookup_name: # Perhaps a real email address
572 lookup_name = lookup_name.lower()
573 col = terminal.Color()
577 msg = "Recursive email alias at '%s'" % lookup_name
581 print(col.Color(col.RED, msg))
585 if not lookup_name in alias:
586 msg = "Alias '%s' not found" % lookup_name
588 raise ValueError(msg)
590 print(col.Color(col.RED, msg))
592 for item in alias[lookup_name]:
593 todo = LookupEmail(item, alias, raise_on_error, level + 1)
594 for new_item in todo:
595 if not new_item in out_list:
596 out_list.append(new_item)
598 #print("No match for alias '%s'" % lookup_name)
602 """Return name of top-level directory for this git repo.
605 Full path to git top-level directory
607 This test makes sure that we are running tests in the right subdir
609 >>> os.path.realpath(os.path.dirname(__file__)) == \
610 os.path.join(GetTopLevel(), 'tools', 'patman')
613 return command.OutputOneLine('git', 'rev-parse', '--show-toplevel')
616 """Gets the name of the git alias file.
619 Filename of git alias file, or None if none
621 fname = command.OutputOneLine('git', 'config', 'sendemail.aliasesfile',
622 raise_on_error=False)
624 fname = os.path.join(GetTopLevel(), fname.strip())
627 def GetDefaultUserName():
628 """Gets the user.name from .gitconfig file.
631 User name found in .gitconfig file, or None if none
633 uname = command.OutputOneLine('git', 'config', '--global', 'user.name')
636 def GetDefaultUserEmail():
637 """Gets the user.email from the global .gitconfig file.
640 User's email found in .gitconfig file, or None if none
642 uemail = command.OutputOneLine('git', 'config', '--global', 'user.email')
645 def GetDefaultSubjectPrefix():
646 """Gets the format.subjectprefix from local .git/config file.
649 Subject prefix found in local .git/config file, or None if none
651 sub_prefix = command.OutputOneLine('git', 'config', 'format.subjectprefix',
652 raise_on_error=False)
657 """Set up git utils, by reading the alias files."""
658 # Check for a git alias file also
659 global use_no_decorate
661 alias_fname = GetAliasFile()
663 settings.ReadGitAliases(alias_fname)
664 cmd = LogCmd(None, count=0)
665 use_no_decorate = (command.RunPipe([cmd], raise_on_error=False)
669 """Get the hash of the current HEAD
674 return command.OutputOneLine('git', 'show', '-s', '--pretty=format:%H')
676 if __name__ == "__main__":