mirror of
https://gitlab.postmarketos.org/postmarketOS/pmbootstrap.git
synced 2025-07-13 03:19:47 +03:00
pmb.*: various comment reformatting to assist with generating docs (MR 2266)
This commit is contained in:
Robert Eckelmann
Newbyte
parent
415e7364f4
commit
044d3b5a6a
43 changed files with 592 additions and 599 deletions
|
|
@ -12,22 +12,25 @@ import pmb.helpers.run
|
|||
|
||||
|
||||
def get_path(args, name_repo):
|
||||
""" Get the path to the repository, which is either the default one in the
|
||||
work dir, or a user-specified one in args.
|
||||
"""Get the path to the repository.
|
||||
|
||||
:returns: full path to repository """
|
||||
The path is either the default one in the work dir, or a user-specified one in args.
|
||||
|
||||
:returns: full path to repository
|
||||
"""
|
||||
if name_repo == "pmaports":
|
||||
return args.aports
|
||||
return args.work + "/cache_git/" + name_repo
|
||||
|
||||
|
||||
def clone(args, name_repo):
|
||||
""" Clone a git repository to $WORK/cache_git/$name_repo (or to the
|
||||
overridden path set in args, as with pmbootstrap --aports).
|
||||
"""Clone a git repository to $WORK/cache_git/$name_repo.
|
||||
|
||||
:param name_repo: short alias used for the repository name, from
|
||||
pmb.config.git_repos (e.g. "aports_upstream",
|
||||
"pmaports") """
|
||||
(or to the overridden path set in args, as with ``pmbootstrap --aports``).
|
||||
|
||||
:param name_repo: short alias used for the repository name, from pmb.config.git_repos
|
||||
(e.g. "aports_upstream", "pmaports")
|
||||
"""
|
||||
# Check for repo name in the config
|
||||
if name_repo not in pmb.config.git_repos:
|
||||
raise ValueError("No git repository configured for " + name_repo)
|
||||
|
|
@ -52,14 +55,14 @@ def clone(args, name_repo):
|
|||
|
||||
|
||||
def rev_parse(args, path, revision="HEAD", extra_args: list = []):
|
||||
""" Run "git rev-parse" in a specific repository dir.
|
||||
"""Run "git rev-parse" in a specific repository dir.
|
||||
|
||||
:param path: to the git repository
|
||||
:param extra_args: additional arguments for "git rev-parse". Pass
|
||||
"--abbrev-ref" to get the branch instead of the
|
||||
commit, if possible.
|
||||
:returns: commit string like "90cd0ad84d390897efdcf881c0315747a4f3a966"
|
||||
or (with --abbrev-ref): the branch name, e.g. "master" """
|
||||
:param path: to the git repository
|
||||
:param extra_args: additional arguments for ``git rev-parse``. Pass
|
||||
``--abbrev-ref`` to get the branch instead of the commit, if possible.
|
||||
:returns: commit string like "90cd0ad84d390897efdcf881c0315747a4f3a966"
|
||||
or (with ``--abbrev-ref``): the branch name, e.g. "master"
|
||||
"""
|
||||
command = ["git", "rev-parse"] + extra_args + [revision]
|
||||
rev = pmb.helpers.run.user(args, command, path, output_return=True)
|
||||
return rev.rstrip()
|
||||
|
|
@ -77,15 +80,16 @@ def can_fast_forward(args, path, branch_upstream, branch="HEAD"):
|
|||
|
||||
|
||||
def clean_worktree(args, path):
|
||||
""" Check if there are not any modified files in the git dir. """
|
||||
"""Check if there are not any modified files in the git dir."""
|
||||
command = ["git", "status", "--porcelain"]
|
||||
return pmb.helpers.run.user(args, command, path, output_return=True) == ""
|
||||
|
||||
|
||||
def get_upstream_remote(args, name_repo):
|
||||
""" Find the remote, which matches the git URL from the config. Usually
|
||||
"origin", but the user may have set up their git repository
|
||||
differently. """
|
||||
"""Find the remote, which matches the git URL from the config.
|
||||
|
||||
Usually "origin", but the user may have set up their git repository differently.
|
||||
"""
|
||||
url = pmb.config.git_repos[name_repo]
|
||||
path = get_path(args, name_repo)
|
||||
command = ["git", "remote", "-v"]
|
||||
|
|
@ -98,14 +102,17 @@ def get_upstream_remote(args, name_repo):
|
|||
|
||||
|
||||
def parse_channels_cfg(args):
|
||||
""" Parse channels.cfg from pmaports.git, origin/master branch.
|
||||
Reference: https://postmarketos.org/channels.cfg
|
||||
:returns: dict like: {"meta": {"recommended": "edge"},
|
||||
"channels": {"edge": {"description": ...,
|
||||
"branch_pmaports": ...,
|
||||
"branch_aports": ...,
|
||||
"mirrordir_alpine": ...},
|
||||
...}} """
|
||||
"""Parse channels.cfg from pmaports.git, origin/master branch.
|
||||
|
||||
Reference: https://postmarketos.org/channels.cfg
|
||||
|
||||
:returns: dict like: {"meta": {"recommended": "edge"},
|
||||
"channels": {"edge": {"description": ...,
|
||||
"branch_pmaports": ...,
|
||||
"branch_aports": ...,
|
||||
"mirrordir_alpine": ...},
|
||||
...}}
|
||||
"""
|
||||
# Cache during one pmbootstrap run
|
||||
cache_key = "pmb.helpers.git.parse_channels_cfg"
|
||||
if pmb.helpers.other.cache[cache_key]:
|
||||
|
|
@ -151,8 +158,10 @@ def parse_channels_cfg(args):
|
|||
|
||||
|
||||
def get_branches_official(args, name_repo):
|
||||
""" Get all branches that point to official release channels.
|
||||
:returns: list of supported branches, e.g. ["master", "3.11"] """
|
||||
"""Get all branches that point to official release channels.
|
||||
|
||||
:returns: list of supported branches, e.g. ["master", "3.11"]
|
||||
"""
|
||||
# This functions gets called with pmaports and aports_upstream, because
|
||||
# both are displayed in "pmbootstrap status". But it only makes sense
|
||||
# to display pmaports there, related code will be refactored soon (#1903).
|
||||
|
|
@ -167,12 +176,14 @@ def get_branches_official(args, name_repo):
|
|||
|
||||
|
||||
def pull(args, name_repo):
|
||||
""" Check if on official branch and essentially try 'git pull --ff-only'.
|
||||
Instead of really doing 'git pull --ff-only', do it in multiple steps
|
||||
(fetch, merge --ff-only), so we can display useful messages depending
|
||||
on which part fails.
|
||||
"""Check if on official branch and essentially try ``git pull --ff-only``.
|
||||
|
||||
:returns: integer, >= 0 on success, < 0 on error """
|
||||
Instead of really doing ``git pull --ff-only``, do it in multiple steps
|
||||
(``fetch, merge --ff-only``), so we can display useful messages depending
|
||||
on which part fails.
|
||||
|
||||
:returns: integer, >= 0 on success, < 0 on error
|
||||
"""
|
||||
branches_official = get_branches_official(args, name_repo)
|
||||
|
||||
# Skip if repo wasn't cloned
|
||||
|
|
@ -229,18 +240,24 @@ def pull(args, name_repo):
|
|||
|
||||
|
||||
def get_topdir(args, path):
|
||||
""" :returns: a string with the top dir of the git repository, or an
|
||||
empty string if it's not a git repository. """
|
||||
"""Get top-dir of git repo.
|
||||
|
||||
:returns: a string with the top dir of the git repository,
|
||||
or an empty string if it's not a git repository.
|
||||
"""
|
||||
return pmb.helpers.run.user(args, ["git", "rev-parse", "--show-toplevel"],
|
||||
path, output_return=True, check=False).rstrip()
|
||||
|
||||
|
||||
def get_files(args, path):
|
||||
""" Get all files inside a git repository, that are either already in the
|
||||
git tree or are not in gitignore. Do not list deleted files. To be used
|
||||
for creating a tarball of the git repository.
|
||||
:param path: top dir of the git repository
|
||||
:returns: all files in a git repository as list, relative to path """
|
||||
"""Get all files inside a git repository, that are either already in the git tree or are not in gitignore.
|
||||
|
||||
Do not list deleted files. To be used for creating a tarball of the git repository.
|
||||
|
||||
:param path: top dir of the git repository
|
||||
|
||||
:returns: all files in a git repository as list, relative to path
|
||||
"""
|
||||
ret = []
|
||||
files = pmb.helpers.run.user(args, ["git", "ls-files"], path,
|
||||
output_return=True).split("\n")
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue