Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/git/remote.py: 50%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
2#
3# This module is part of GitPython and is released under the
4# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
6"""Module implementing a remote object allowing easy access to git remotes."""
8__all__ = ["RemoteProgress", "PushInfo", "FetchInfo", "Remote"]
10import contextlib
11import logging
12import re
14from git.cmd import Git, handle_process_output
15from git.compat import defenc, force_text
16from git.config import GitConfigParser, SectionConstraint, cp
17from git.exc import GitCommandError
18from git.refs import Head, Reference, RemoteReference, SymbolicReference, TagReference
19from git.util import (
20 CallableRemoteProgress,
21 IterableList,
22 IterableObj,
23 LazyMixin,
24 RemoteProgress,
25 join_path,
26)
28# typing-------------------------------------------------------
30from typing import (
31 Any,
32 Callable,
33 Dict,
34 Iterator,
35 List,
36 NoReturn,
37 Optional,
38 Sequence,
39 TYPE_CHECKING,
40 Type,
41 Union,
42 cast,
43 overload,
44)
46from git.types import AnyGitObject, Literal, PathLike
48if TYPE_CHECKING:
49 from git.objects.commit import Commit
50 from git.objects.submodule.base import UpdateProgress
51 from git.repo.base import Repo
53flagKeyLiteral = Literal[" ", "!", "+", "-", "*", "=", "t", "?"]
55# -------------------------------------------------------------
57_logger = logging.getLogger(__name__)
59# { Utilities
62def add_progress(
63 kwargs: Any,
64 git: Git,
65 progress: Union[RemoteProgress, "UpdateProgress", Callable[..., RemoteProgress], None],
66) -> Any:
67 """Add the ``--progress`` flag to the given `kwargs` dict if supported by the git
68 command.
70 :note:
71 If the actual progress in the given progress instance is not given, we do not
72 request any progress.
74 :return:
75 Possibly altered `kwargs`
76 """
77 if progress is not None:
78 v = git.version_info[:2]
79 if v >= (1, 7):
80 kwargs["progress"] = True
81 # END handle --progress
82 # END handle progress
83 return kwargs
86# } END utilities
89@overload
90def to_progress_instance(progress: None) -> RemoteProgress: ...
93@overload
94def to_progress_instance(progress: Callable[..., Any]) -> CallableRemoteProgress: ...
97@overload
98def to_progress_instance(progress: RemoteProgress) -> RemoteProgress: ...
101def to_progress_instance(
102 progress: Union[Callable[..., Any], RemoteProgress, None],
103) -> Union[RemoteProgress, CallableRemoteProgress]:
104 """Given the `progress` return a suitable object derived from
105 :class:`~git.util.RemoteProgress`."""
106 # New API only needs progress as a function.
107 if callable(progress):
108 return CallableRemoteProgress(progress)
110 # Where None is passed create a parser that eats the progress.
111 elif progress is None:
112 return RemoteProgress()
114 # Assume its the old API with an instance of RemoteProgress.
115 return progress
118class PushInfo(IterableObj):
119 """
120 Carries information about the result of a push operation of a single head::
122 info = remote.push()[0]
123 info.flags # bitflags providing more information about the result
124 info.local_ref # Reference pointing to the local reference that was pushed
125 # It is None if the ref was deleted.
126 info.remote_ref_string # path to the remote reference located on the remote side
127 info.remote_ref # Remote Reference on the local side corresponding to
128 # the remote_ref_string. It can be a TagReference as well.
129 info.old_commit # commit at which the remote_ref was standing before we pushed
130 # it to local_ref.commit. Will be None if an error was indicated
131 info.summary # summary line providing human readable english text about the push
132 """
134 __slots__ = (
135 "local_ref",
136 "remote_ref_string",
137 "flags",
138 "_old_commit_sha",
139 "_remote",
140 "summary",
141 )
143 _id_attribute_ = "pushinfo"
145 (
146 NEW_TAG,
147 NEW_HEAD,
148 NO_MATCH,
149 REJECTED,
150 REMOTE_REJECTED,
151 REMOTE_FAILURE,
152 DELETED,
153 FORCED_UPDATE,
154 FAST_FORWARD,
155 UP_TO_DATE,
156 ERROR,
157 ) = [1 << x for x in range(11)]
159 _flag_map = {
160 "X": NO_MATCH,
161 "-": DELETED,
162 "*": 0,
163 "+": FORCED_UPDATE,
164 " ": FAST_FORWARD,
165 "=": UP_TO_DATE,
166 "!": ERROR,
167 }
169 def __init__(
170 self,
171 flags: int,
172 local_ref: Union[SymbolicReference, None],
173 remote_ref_string: str,
174 remote: "Remote",
175 old_commit: Optional[str] = None,
176 summary: str = "",
177 ) -> None:
178 """Initialize a new instance.
180 local_ref: HEAD | Head | RemoteReference | TagReference | Reference | SymbolicReference | None
181 """
182 self.flags = flags
183 self.local_ref = local_ref
184 self.remote_ref_string = remote_ref_string
185 self._remote = remote
186 self._old_commit_sha = old_commit
187 self.summary = summary
189 @property
190 def old_commit(self) -> Union["Commit", None]:
191 return self._old_commit_sha and self._remote.repo.commit(self._old_commit_sha) or None
193 @property
194 def remote_ref(self) -> Union[RemoteReference, TagReference]:
195 """
196 :return:
197 Remote :class:`~git.refs.reference.Reference` or
198 :class:`~git.refs.tag.TagReference` in the local repository corresponding to
199 the :attr:`remote_ref_string` kept in this instance.
200 """
201 # Translate heads to a local remote. Tags stay as they are.
202 if self.remote_ref_string.startswith("refs/tags"):
203 return TagReference(self._remote.repo, self.remote_ref_string)
204 elif self.remote_ref_string.startswith("refs/heads"):
205 remote_ref = Reference(self._remote.repo, self.remote_ref_string)
206 return RemoteReference(
207 self._remote.repo,
208 "refs/remotes/%s/%s" % (str(self._remote), remote_ref.name),
209 )
210 else:
211 raise ValueError("Could not handle remote ref: %r" % self.remote_ref_string)
212 # END
214 @classmethod
215 def _from_line(cls, remote: "Remote", line: str) -> "PushInfo":
216 """Create a new :class:`PushInfo` instance as parsed from line which is expected
217 to be like refs/heads/master:refs/heads/master 05d2687..1d0568e as bytes."""
218 control_character, from_to, summary = line.split("\t", 3)
219 flags = 0
221 # Control character handling
222 try:
223 flags |= cls._flag_map[control_character]
224 except KeyError as e:
225 raise ValueError("Control character %r unknown as parsed from line %r" % (control_character, line)) from e
226 # END handle control character
228 # from_to handling
229 from_ref_string, to_ref_string = from_to.split(":")
230 if flags & cls.DELETED:
231 from_ref: Union[SymbolicReference, None] = None
232 else:
233 if from_ref_string == "(delete)":
234 from_ref = None
235 else:
236 from_ref = Reference.from_path(remote.repo, from_ref_string)
238 # Commit handling, could be message or commit info
239 old_commit: Optional[str] = None
240 if summary.startswith("["):
241 if "[rejected]" in summary:
242 flags |= cls.REJECTED
243 elif "[remote rejected]" in summary:
244 flags |= cls.REMOTE_REJECTED
245 elif "[remote failure]" in summary:
246 flags |= cls.REMOTE_FAILURE
247 elif "[no match]" in summary:
248 flags |= cls.ERROR
249 elif "[new tag]" in summary:
250 flags |= cls.NEW_TAG
251 elif "[new branch]" in summary:
252 flags |= cls.NEW_HEAD
253 # `uptodate` encoded in control character
254 else:
255 # Fast-forward or forced update - was encoded in control character,
256 # but we parse the old and new commit.
257 split_token = "..."
258 if control_character == " ":
259 split_token = ".."
260 old_sha, _new_sha = summary.split(" ")[0].split(split_token)
261 # Have to use constructor here as the sha usually is abbreviated.
262 old_commit = old_sha
263 # END message handling
265 return PushInfo(flags, from_ref, to_ref_string, remote, old_commit, summary)
267 @classmethod
268 def iter_items(cls, repo: "Repo", *args: Any, **kwargs: Any) -> NoReturn: # -> Iterator['PushInfo']:
269 raise NotImplementedError
272class PushInfoList(IterableList[PushInfo]):
273 """:class:`~git.util.IterableList` of :class:`PushInfo` objects."""
275 def __new__(cls) -> "PushInfoList":
276 return cast(PushInfoList, IterableList.__new__(cls, "push_infos"))
278 def __init__(self) -> None:
279 super().__init__("push_infos")
280 self.error: Optional[Exception] = None
282 def raise_if_error(self) -> None:
283 """Raise an exception if any ref failed to push."""
284 if self.error:
285 raise self.error
288class FetchInfo(IterableObj):
289 """
290 Carries information about the results of a fetch operation of a single head::
292 info = remote.fetch()[0]
293 info.ref # Symbolic Reference or RemoteReference to the changed
294 # remote head or FETCH_HEAD
295 info.flags # additional flags to be & with enumeration members,
296 # i.e. info.flags & info.REJECTED
297 # is 0 if ref is SymbolicReference
298 info.note # additional notes given by git-fetch intended for the user
299 info.old_commit # if info.flags & info.FORCED_UPDATE|info.FAST_FORWARD,
300 # field is set to the previous location of ref, otherwise None
301 info.remote_ref_path # The path from which we fetched on the remote. It's the remote's version of our info.ref
302 """
304 __slots__ = ("ref", "old_commit", "flags", "note", "remote_ref_path")
306 _id_attribute_ = "fetchinfo"
308 (
309 NEW_TAG,
310 NEW_HEAD,
311 HEAD_UPTODATE,
312 TAG_UPDATE,
313 REJECTED,
314 FORCED_UPDATE,
315 FAST_FORWARD,
316 ERROR,
317 ) = [1 << x for x in range(8)]
319 _re_fetch_result = re.compile(r"^ *(?:.{0,3})(.) (\[[\w \.$@]+\]|[\w\.$@]+) +(.+) -> ([^ ]+)( \(.*\)?$)?")
321 _flag_map: Dict[flagKeyLiteral, int] = {
322 "!": ERROR,
323 "+": FORCED_UPDATE,
324 "*": 0,
325 "=": HEAD_UPTODATE,
326 " ": FAST_FORWARD,
327 "-": TAG_UPDATE,
328 }
330 @classmethod
331 def refresh(cls) -> Literal[True]:
332 """Update information about which :manpage:`git-fetch(1)` flags are supported
333 by the git executable being used.
335 Called by the :func:`git.refresh` function in the top level ``__init__``.
336 """
337 # Clear the old values in _flag_map.
338 with contextlib.suppress(KeyError):
339 del cls._flag_map["t"]
340 with contextlib.suppress(KeyError):
341 del cls._flag_map["-"]
343 # Set the value given the git version.
344 if Git().version_info[:2] >= (2, 10):
345 cls._flag_map["t"] = cls.TAG_UPDATE
346 else:
347 cls._flag_map["-"] = cls.TAG_UPDATE
349 return True
351 def __init__(
352 self,
353 ref: SymbolicReference,
354 flags: int,
355 note: str = "",
356 old_commit: Union[AnyGitObject, None] = None,
357 remote_ref_path: Optional[PathLike] = None,
358 ) -> None:
359 """Initialize a new instance."""
360 self.ref = ref
361 self.flags = flags
362 self.note = note
363 self.old_commit = old_commit
364 self.remote_ref_path = remote_ref_path
366 def __str__(self) -> str:
367 return self.name
369 @property
370 def name(self) -> str:
371 """:return: Name of our remote ref"""
372 return self.ref.name
374 @property
375 def commit(self) -> "Commit":
376 """:return: Commit of our remote ref"""
377 return self.ref.commit
379 @classmethod
380 def _from_line(cls, repo: "Repo", line: str, fetch_line: str) -> "FetchInfo":
381 """Parse information from the given line as returned by ``git-fetch -v`` and
382 return a new :class:`FetchInfo` object representing this information.
384 We can handle a line as follows::
386 %c %-*s %-*s -> %s%s
388 Where ``c`` is either a space, ``!``, ``+``, ``-``, ``*``, or ``=``:
390 - '!' means error
391 - '+' means success forcing update
392 - '-' means a tag was updated
393 - '*' means birth of new branch or tag
394 - '=' means the head was up to date (and not moved)
395 - ' ' means a fast-forward
397 `fetch_line` is the corresponding line from FETCH_HEAD, like::
399 acb0fa8b94ef421ad60c8507b634759a472cd56c not-for-merge branch '0.1.7RC' of /tmp/tmpya0vairemote_repo
400 """
401 match = cls._re_fetch_result.match(line)
402 if match is None:
403 raise ValueError("Failed to parse line: %r" % line)
405 # Parse lines.
406 remote_local_ref_str: str
407 (
408 control_character,
409 operation,
410 local_remote_ref,
411 remote_local_ref_str,
412 note,
413 ) = match.groups()
414 control_character = cast(flagKeyLiteral, control_character)
415 try:
416 _new_hex_sha, _fetch_operation, fetch_note = fetch_line.split("\t")
417 ref_type_name, fetch_note = fetch_note.split(" ", 1)
418 except ValueError as e: # unpack error
419 raise ValueError("Failed to parse FETCH_HEAD line: %r" % fetch_line) from e
421 # Parse flags from control_character.
422 flags = 0
423 try:
424 flags |= cls._flag_map[control_character]
425 except KeyError as e:
426 raise ValueError("Control character %r unknown as parsed from line %r" % (control_character, line)) from e
427 # END control char exception handling
429 # Parse operation string for more info.
430 # This makes no sense for symbolic refs, but we parse it anyway.
431 old_commit: Union[AnyGitObject, None] = None
432 is_tag_operation = False
433 if "rejected" in operation:
434 flags |= cls.REJECTED
435 if "new tag" in operation:
436 flags |= cls.NEW_TAG
437 is_tag_operation = True
438 if "tag update" in operation:
439 flags |= cls.TAG_UPDATE
440 is_tag_operation = True
441 if "new branch" in operation:
442 flags |= cls.NEW_HEAD
443 if "..." in operation or ".." in operation:
444 split_token = "..."
445 if control_character == " ":
446 split_token = split_token[:-1]
447 old_commit = repo.rev_parse(operation.split(split_token)[0])
448 # END handle refspec
450 # Handle FETCH_HEAD and figure out ref type.
451 # If we do not specify a target branch like master:refs/remotes/origin/master,
452 # the fetch result is stored in FETCH_HEAD which destroys the rule we usually
453 # have. In that case we use a symbolic reference which is detached.
454 ref_type: Optional[Type[SymbolicReference]] = None
455 if remote_local_ref_str == "FETCH_HEAD":
456 ref_type = SymbolicReference
457 elif ref_type_name == "tag" or is_tag_operation:
458 # The ref_type_name can be branch, whereas we are still seeing a tag
459 # operation. It happens during testing, which is based on actual git
460 # operations.
461 ref_type = TagReference
462 elif ref_type_name in ("remote-tracking", "branch"):
463 # Note: remote-tracking is just the first part of the
464 # 'remote-tracking branch' token. We don't parse it correctly, but it's
465 # enough to know what to do, and it's new in git 1.7something.
466 ref_type = RemoteReference
467 elif "/" in ref_type_name:
468 # If the fetch spec look something like '+refs/pull/*:refs/heads/pull/*',
469 # and is thus pretty much anything the user wants, we will have trouble
470 # determining what's going on. For now, we assume the local ref is a Head.
471 ref_type = Head
472 else:
473 raise TypeError("Cannot handle reference type: %r" % ref_type_name)
474 # END handle ref type
476 # Create ref instance.
477 if ref_type is SymbolicReference:
478 remote_local_ref = ref_type(repo, "FETCH_HEAD")
479 else:
480 # Determine prefix. Tags are usually pulled into refs/tags; they may have
481 # subdirectories. It is not clear sometimes where exactly the item is,
482 # unless we have an absolute path as indicated by the 'ref/' prefix.
483 # Otherwise even a tag could be in refs/remotes, which is when it will have
484 # the 'tags/' subdirectory in its path. We don't want to test for actual
485 # existence, but try to figure everything out analytically.
486 ref_path: Optional[PathLike] = None
487 remote_local_ref_str = remote_local_ref_str.strip()
489 if remote_local_ref_str.startswith(Reference._common_path_default + "/"):
490 # Always use actual type if we get absolute paths. This will always be
491 # the case if something is fetched outside of refs/remotes (if its not a
492 # tag).
493 ref_path = remote_local_ref_str
494 if ref_type is not TagReference and not remote_local_ref_str.startswith(
495 RemoteReference._common_path_default + "/"
496 ):
497 ref_type = Reference
498 # END downgrade remote reference
499 elif ref_type is TagReference and "tags/" in remote_local_ref_str:
500 # Even though it's a tag, it is located in refs/remotes.
501 ref_path = join_path(RemoteReference._common_path_default, remote_local_ref_str)
502 else:
503 ref_path = join_path(ref_type._common_path_default, remote_local_ref_str)
504 # END obtain refpath
506 # Even though the path could be within the git conventions, we make sure we
507 # respect whatever the user wanted, and disabled path checking.
508 remote_local_ref = ref_type(repo, ref_path, check_path=False)
509 # END create ref instance
511 note = (note and note.strip()) or ""
513 return cls(remote_local_ref, flags, note, old_commit, local_remote_ref)
515 @classmethod
516 def iter_items(cls, repo: "Repo", *args: Any, **kwargs: Any) -> NoReturn: # -> Iterator['FetchInfo']:
517 raise NotImplementedError
520class Remote(LazyMixin, IterableObj):
521 """Provides easy read and write access to a git remote.
523 Everything not part of this interface is considered an option for the current
524 remote, allowing constructs like ``remote.pushurl`` to query the pushurl.
526 :note:
527 When querying configuration, the configuration accessor will be cached to speed
528 up subsequent accesses.
529 """
531 __slots__ = ("repo", "name", "_config_reader")
533 _id_attribute_ = "name"
535 unsafe_git_fetch_options = [
536 # This option allows users to execute arbitrary commands.
537 # https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt---upload-packltupload-packgt
538 "--upload-pack",
539 ]
540 unsafe_git_pull_options = [
541 # This option allows users to execute arbitrary commands.
542 # https://git-scm.com/docs/git-pull#Documentation/git-pull.txt---upload-packltupload-packgt
543 "--upload-pack"
544 ]
545 unsafe_git_push_options = [
546 # This option allows users to execute arbitrary commands.
547 # https://git-scm.com/docs/git-push#Documentation/git-push.txt---execltgit-receive-packgt
548 "--receive-pack",
549 "--exec",
550 ]
552 url: str # Obtained dynamically from _config_reader. See __getattr__ below.
553 """The URL configured for the remote."""
555 def __init__(self, repo: "Repo", name: str) -> None:
556 """Initialize a remote instance.
558 :param repo:
559 The repository we are a remote of.
561 :param name:
562 The name of the remote, e.g. ``origin``.
563 """
564 self.repo = repo
565 self.name = name
567 def __getattr__(self, attr: str) -> Any:
568 """Allows to call this instance like ``remote.special(*args, **kwargs)`` to
569 call ``git remote special self.name``."""
570 if attr == "_config_reader":
571 return super().__getattr__(attr)
573 # Sometimes, probably due to a bug in Python itself, we are being called even
574 # though a slot of the same name exists.
575 try:
576 return self._config_reader.get(attr)
577 except cp.NoOptionError:
578 return super().__getattr__(attr)
579 # END handle exception
581 def _config_section_name(self) -> str:
582 return 'remote "%s"' % self.name
584 def _set_cache_(self, attr: str) -> None:
585 if attr == "_config_reader":
586 # NOTE: This is cached as __getattr__ is overridden to return remote config
587 # values implicitly, such as in print(r.pushurl).
588 self._config_reader = SectionConstraint(
589 self.repo.config_reader("repository"),
590 self._config_section_name(),
591 )
592 else:
593 super()._set_cache_(attr)
595 def __str__(self) -> str:
596 return self.name
598 def __repr__(self) -> str:
599 return '<git.%s "%s">' % (self.__class__.__name__, self.name)
601 def __eq__(self, other: object) -> bool:
602 return isinstance(other, type(self)) and self.name == other.name
604 def __ne__(self, other: object) -> bool:
605 return not (self == other)
607 def __hash__(self) -> int:
608 return hash(self.name)
610 def exists(self) -> bool:
611 """
612 :return:
613 ``True`` if this is a valid, existing remote.
614 Valid remotes have an entry in the repository's configuration.
615 """
616 try:
617 self.config_reader.get("url")
618 return True
619 except cp.NoOptionError:
620 # We have the section at least...
621 return True
622 except cp.NoSectionError:
623 return False
625 @classmethod
626 def iter_items(cls, repo: "Repo", *args: Any, **kwargs: Any) -> Iterator["Remote"]:
627 """:return: Iterator yielding :class:`Remote` objects of the given repository"""
628 for section in repo.config_reader("repository").sections():
629 if not section.startswith("remote "):
630 continue
631 lbound = section.find('"')
632 rbound = section.rfind('"')
633 if lbound == -1 or rbound == -1:
634 raise ValueError("Remote-Section has invalid format: %r" % section)
635 yield Remote(repo, section[lbound + 1 : rbound])
636 # END for each configuration section
638 def set_url(
639 self, new_url: str, old_url: Optional[str] = None, allow_unsafe_protocols: bool = False, **kwargs: Any
640 ) -> "Remote":
641 """Configure URLs on current remote (cf. command ``git remote set-url``).
643 This command manages URLs on the remote.
645 :param new_url:
646 String being the URL to add as an extra remote URL.
648 :param old_url:
649 When set, replaces this URL with `new_url` for the remote.
651 :param allow_unsafe_protocols:
652 Allow unsafe protocols to be used, like ``ext``.
654 :return:
655 self
656 """
657 if not allow_unsafe_protocols:
658 Git.check_unsafe_protocols(new_url)
659 scmd = "set-url"
660 kwargs["insert_kwargs_after"] = scmd
661 if old_url:
662 self.repo.git.remote(scmd, "--", self.name, new_url, old_url, **kwargs)
663 else:
664 self.repo.git.remote(scmd, "--", self.name, new_url, **kwargs)
665 return self
667 def add_url(self, url: str, allow_unsafe_protocols: bool = False, **kwargs: Any) -> "Remote":
668 """Adds a new url on current remote (special case of ``git remote set-url``).
670 This command adds new URLs to a given remote, making it possible to have
671 multiple URLs for a single remote.
673 :param url:
674 String being the URL to add as an extra remote URL.
676 :param allow_unsafe_protocols:
677 Allow unsafe protocols to be used, like ``ext``.
679 :return:
680 self
681 """
682 return self.set_url(url, add=True, allow_unsafe_protocols=allow_unsafe_protocols)
684 def delete_url(self, url: str, **kwargs: Any) -> "Remote":
685 """Deletes a new url on current remote (special case of ``git remote set-url``).
687 This command deletes new URLs to a given remote, making it possible to have
688 multiple URLs for a single remote.
690 :param url:
691 String being the URL to delete from the remote.
693 :return:
694 self
695 """
696 return self.set_url(url, delete=True)
698 @property
699 def urls(self) -> Iterator[str]:
700 """:return: Iterator yielding all configured URL targets on a remote as strings"""
701 try:
702 remote_details = self.repo.git.remote("get-url", "--all", self.name)
703 assert isinstance(remote_details, str)
704 for line in remote_details.split("\n"):
705 yield line
706 except GitCommandError as ex:
707 ## We are on git < 2.7 (i.e TravisCI as of Oct-2016),
708 # so `get-utl` command does not exist yet!
709 # see: https://github.com/gitpython-developers/GitPython/pull/528#issuecomment-252976319
710 # and: http://stackoverflow.com/a/32991784/548792
711 #
712 if "Unknown subcommand: get-url" in str(ex):
713 try:
714 remote_details = self.repo.git.remote("show", self.name)
715 assert isinstance(remote_details, str)
716 for line in remote_details.split("\n"):
717 if " Push URL:" in line:
718 yield line.split(": ")[-1]
719 except GitCommandError as _ex:
720 if any(msg in str(_ex) for msg in ["correct access rights", "cannot run ssh"]):
721 # If ssh is not setup to access this repository, see issue 694.
722 remote_details = self.repo.git.config("--get-all", "remote.%s.url" % self.name)
723 assert isinstance(remote_details, str)
724 for line in remote_details.split("\n"):
725 yield line
726 else:
727 raise _ex
728 else:
729 raise ex
731 @property
732 def refs(self) -> IterableList[RemoteReference]:
733 """
734 :return:
735 :class:`~git.util.IterableList` of :class:`~git.refs.remote.RemoteReference`
736 objects.
738 It is prefixed, allowing you to omit the remote path portion, e.g.::
740 remote.refs.master # yields RemoteReference('/refs/remotes/origin/master')
741 """
742 out_refs: IterableList[RemoteReference] = IterableList(RemoteReference._id_attribute_, "%s/" % self.name)
743 out_refs.extend(RemoteReference.list_items(self.repo, remote=self.name))
744 return out_refs
746 @property
747 def stale_refs(self) -> IterableList[Reference]:
748 """
749 :return:
750 :class:`~git.util.IterableList` of :class:`~git.refs.remote.RemoteReference`
751 objects that do not have a corresponding head in the remote reference
752 anymore as they have been deleted on the remote side, but are still
753 available locally.
755 The :class:`~git.util.IterableList` is prefixed, hence the 'origin' must be
756 omitted. See :attr:`refs` property for an example.
758 To make things more complicated, it can be possible for the list to include
759 other kinds of references, for example, tag references, if these are stale
760 as well. This is a fix for the issue described here:
761 https://github.com/gitpython-developers/GitPython/issues/260
762 """
763 out_refs: IterableList[Reference] = IterableList(RemoteReference._id_attribute_, "%s/" % self.name)
764 for line in self.repo.git.remote("prune", "--dry-run", self).splitlines()[2:]:
765 # expecting
766 # * [would prune] origin/new_branch
767 token = " * [would prune] "
768 if not line.startswith(token):
769 continue
770 ref_name = line.replace(token, "")
771 # Sometimes, paths start with a full ref name, like refs/tags/foo. See #260.
772 if ref_name.startswith(Reference._common_path_default + "/"):
773 out_refs.append(Reference.from_path(self.repo, ref_name))
774 else:
775 fqhn = "%s/%s" % (RemoteReference._common_path_default, ref_name)
776 out_refs.append(RemoteReference(self.repo, fqhn))
777 # END special case handling
778 # END for each line
779 return out_refs
781 @classmethod
782 def create(cls, repo: "Repo", name: str, url: str, allow_unsafe_protocols: bool = False, **kwargs: Any) -> "Remote":
783 """Create a new remote to the given repository.
785 :param repo:
786 Repository instance that is to receive the new remote.
788 :param name:
789 Desired name of the remote.
791 :param url:
792 URL which corresponds to the remote's name.
794 :param allow_unsafe_protocols:
795 Allow unsafe protocols to be used, like ``ext``.
797 :param kwargs:
798 Additional arguments to be passed to the ``git remote add`` command.
800 :return:
801 New :class:`Remote` instance
803 :raise git.exc.GitCommandError:
804 In case an origin with that name already exists.
805 """
806 scmd = "add"
807 kwargs["insert_kwargs_after"] = scmd
808 url = Git.polish_url(url)
809 if not allow_unsafe_protocols:
810 Git.check_unsafe_protocols(url)
811 repo.git.remote(scmd, "--", name, url, **kwargs)
812 return cls(repo, name)
814 # `add` is an alias.
815 @classmethod
816 def add(cls, repo: "Repo", name: str, url: str, **kwargs: Any) -> "Remote":
817 return cls.create(repo, name, url, **kwargs)
819 @classmethod
820 def remove(cls, repo: "Repo", name: str) -> str:
821 """Remove the remote with the given name.
823 :return:
824 The passed remote name to remove
825 """
826 repo.git.remote("rm", name)
827 if isinstance(name, cls):
828 name._clear_cache()
829 return name
831 @classmethod
832 def rm(cls, repo: "Repo", name: str) -> str:
833 """Alias of remove.
834 Remove the remote with the given name.
836 :return:
837 The passed remote name to remove
838 """
839 return cls.remove(repo, name)
841 def rename(self, new_name: str) -> "Remote":
842 """Rename self to the given `new_name`.
844 :return:
845 self
846 """
847 if self.name == new_name:
848 return self
850 self.repo.git.remote("rename", self.name, new_name)
851 self.name = new_name
852 self._clear_cache()
854 return self
856 def update(self, **kwargs: Any) -> "Remote":
857 """Fetch all changes for this remote, including new branches which will be
858 forced in (in case your local remote branch is not part the new remote branch's
859 ancestry anymore).
861 :param kwargs:
862 Additional arguments passed to ``git remote update``.
864 :return:
865 self
866 """
867 scmd = "update"
868 kwargs["insert_kwargs_after"] = scmd
869 self.repo.git.remote(scmd, self.name, **kwargs)
870 return self
872 def _get_fetch_info_from_stderr(
873 self,
874 proc: "Git.AutoInterrupt",
875 progress: Union[Callable[..., Any], RemoteProgress, None],
876 kill_after_timeout: Union[None, float] = None,
877 ) -> IterableList["FetchInfo"]:
878 progress = to_progress_instance(progress)
880 # Skip first line as it is some remote info we are not interested in.
881 output: IterableList["FetchInfo"] = IterableList("name")
883 # Lines which are no progress are fetch info lines.
884 # This also waits for the command to finish.
885 # Skip some progress lines that don't provide relevant information.
886 fetch_info_lines = []
887 # Basically we want all fetch info lines which appear to be in regular form, and
888 # thus have a command character. Everything else we ignore.
889 cmds = set(FetchInfo._flag_map.keys())
891 progress_handler = progress.new_message_handler()
892 handle_process_output(
893 proc,
894 None,
895 progress_handler,
896 finalizer=None,
897 decode_streams=True,
898 kill_after_timeout=kill_after_timeout,
899 )
901 stderr_text = progress.error_lines and "\n".join(progress.error_lines) or ""
902 proc.wait(stderr=stderr_text)
903 if stderr_text:
904 _logger.warning("Error lines received while fetching: %s", stderr_text)
906 for line in progress.other_lines:
907 line = force_text(line)
908 for cmd in cmds:
909 if len(line) > 1 and line[0] == " " and line[1] == cmd:
910 fetch_info_lines.append(line)
911 continue
913 # Read head information.
914 fetch_head = SymbolicReference(self.repo, "FETCH_HEAD")
915 with open(fetch_head.abspath, "rb") as fp:
916 fetch_head_info = [line.decode(defenc) for line in fp.readlines()]
918 l_fil = len(fetch_info_lines)
919 l_fhi = len(fetch_head_info)
920 if l_fil != l_fhi:
921 msg = "Fetch head lines do not match lines provided via progress information\n"
922 msg += "length of progress lines %i should be equal to lines in FETCH_HEAD file %i\n"
923 msg += "Will ignore extra progress lines or fetch head lines."
924 msg %= (l_fil, l_fhi)
925 _logger.debug(msg)
926 _logger.debug(b"info lines: " + str(fetch_info_lines).encode("UTF-8"))
927 _logger.debug(b"head info: " + str(fetch_head_info).encode("UTF-8"))
928 if l_fil < l_fhi:
929 fetch_head_info = fetch_head_info[:l_fil]
930 else:
931 fetch_info_lines = fetch_info_lines[:l_fhi]
932 # END truncate correct list
933 # END sanity check + sanitization
935 for err_line, fetch_line in zip(fetch_info_lines, fetch_head_info):
936 try:
937 output.append(FetchInfo._from_line(self.repo, err_line, fetch_line))
938 except ValueError as exc:
939 _logger.debug("Caught error while parsing line: %s", exc)
940 _logger.warning("Git informed while fetching: %s", err_line.strip())
941 return output
943 def _get_push_info(
944 self,
945 proc: "Git.AutoInterrupt",
946 progress: Union[Callable[..., Any], RemoteProgress, None],
947 kill_after_timeout: Union[None, float] = None,
948 ) -> PushInfoList:
949 progress = to_progress_instance(progress)
951 # Read progress information from stderr.
952 # We hope stdout can hold all the data, it should...
953 # Read the lines manually as it will use carriage returns between the messages
954 # to override the previous one. This is why we read the bytes manually.
955 progress_handler = progress.new_message_handler()
956 output: PushInfoList = PushInfoList()
958 def stdout_handler(line: str) -> None:
959 try:
960 output.append(PushInfo._from_line(self, line))
961 except ValueError:
962 # If an error happens, additional info is given which we parse below.
963 pass
965 handle_process_output(
966 proc,
967 stdout_handler,
968 progress_handler,
969 finalizer=None,
970 decode_streams=False,
971 kill_after_timeout=kill_after_timeout,
972 )
973 stderr_text = progress.error_lines and "\n".join(progress.error_lines) or ""
974 try:
975 proc.wait(stderr=stderr_text)
976 except Exception as e:
977 # This is different than fetch (which fails if there is any stderr
978 # even if there is an output).
979 if not output:
980 raise
981 elif stderr_text:
982 _logger.warning("Error lines received while fetching: %s", stderr_text)
983 output.error = e
985 return output
987 def _assert_refspec(self) -> None:
988 """Turns out we can't deal with remotes if the refspec is missing."""
989 config = self.config_reader
990 unset = "placeholder"
991 try:
992 if config.get_value("fetch", default=unset) is unset:
993 msg = "Remote '%s' has no refspec set.\n"
994 msg += "You can set it as follows:"
995 msg += " 'git config --add \"remote.%s.fetch +refs/heads/*:refs/heads/*\"'."
996 raise AssertionError(msg % (self.name, self.name))
997 finally:
998 config.release()
1000 def fetch(
1001 self,
1002 refspec: Union[str, List[str], None] = None,
1003 progress: Union[RemoteProgress, None, "UpdateProgress"] = None,
1004 verbose: bool = True,
1005 kill_after_timeout: Union[None, float] = None,
1006 allow_unsafe_protocols: bool = False,
1007 allow_unsafe_options: bool = False,
1008 **kwargs: Any,
1009 ) -> IterableList[FetchInfo]:
1010 """Fetch the latest changes for this remote.
1012 :param refspec:
1013 A "refspec" is used by fetch and push to describe the mapping
1014 between remote ref and local ref. They are combined with a colon in
1015 the format ``<src>:<dst>``, preceded by an optional plus sign, ``+``.
1016 For example: ``git fetch $URL refs/heads/master:refs/heads/origin`` means
1017 "grab the master branch head from the $URL and store it as my origin
1018 branch head". And ``git push $URL refs/heads/master:refs/heads/to-upstream``
1019 means "publish my master branch head as to-upstream branch at $URL".
1020 See also :manpage:`git-push(1)`.
1022 Taken from the git manual, :manpage:`gitglossary(7)`.
1024 Fetch supports multiple refspecs (as the underlying :manpage:`git-fetch(1)`
1025 does) - supplying a list rather than a string for 'refspec' will make use of
1026 this facility.
1028 :param progress:
1029 See the :meth:`push` method.
1031 :param verbose:
1032 Boolean for verbose output.
1034 :param kill_after_timeout:
1035 To specify a timeout in seconds for the git command, after which the process
1036 should be killed. It is set to ``None`` by default.
1038 :param allow_unsafe_protocols:
1039 Allow unsafe protocols to be used, like ``ext``.
1041 :param allow_unsafe_options:
1042 Allow unsafe options to be used, like ``--upload-pack``.
1044 :param kwargs:
1045 Additional arguments to be passed to :manpage:`git-fetch(1)`.
1047 :return:
1048 IterableList(FetchInfo, ...) list of :class:`FetchInfo` instances providing
1049 detailed information about the fetch results
1051 :note:
1052 As fetch does not provide progress information to non-ttys, we cannot make
1053 it available here unfortunately as in the :meth:`push` method.
1054 """
1055 if refspec is None:
1056 # No argument refspec, then ensure the repo's config has a fetch refspec.
1057 self._assert_refspec()
1059 kwargs = add_progress(kwargs, self.repo.git, progress)
1060 if isinstance(refspec, list):
1061 args: Sequence[Optional[str]] = refspec
1062 else:
1063 args = [refspec]
1065 if not allow_unsafe_protocols:
1066 for ref in args:
1067 if ref:
1068 Git.check_unsafe_protocols(ref)
1070 if not allow_unsafe_options:
1071 Git.check_unsafe_options(options=list(kwargs.keys()), unsafe_options=self.unsafe_git_fetch_options)
1073 proc = self.repo.git.fetch(
1074 "--", self, *args, as_process=True, with_stdout=False, universal_newlines=False, v=verbose, **kwargs
1075 )
1076 res = self._get_fetch_info_from_stderr(proc, progress, kill_after_timeout=kill_after_timeout)
1077 if hasattr(self.repo.odb, "update_cache"):
1078 self.repo.odb.update_cache()
1079 return res
1081 def pull(
1082 self,
1083 refspec: Union[str, List[str], None] = None,
1084 progress: Union[RemoteProgress, "UpdateProgress", None] = None,
1085 kill_after_timeout: Union[None, float] = None,
1086 allow_unsafe_protocols: bool = False,
1087 allow_unsafe_options: bool = False,
1088 **kwargs: Any,
1089 ) -> IterableList[FetchInfo]:
1090 """Pull changes from the given branch, being the same as a fetch followed by a
1091 merge of branch with your local branch.
1093 :param refspec:
1094 See :meth:`fetch` method.
1096 :param progress:
1097 See :meth:`push` method.
1099 :param kill_after_timeout:
1100 See :meth:`fetch` method.
1102 :param allow_unsafe_protocols:
1103 Allow unsafe protocols to be used, like ``ext``.
1105 :param allow_unsafe_options:
1106 Allow unsafe options to be used, like ``--upload-pack``.
1108 :param kwargs:
1109 Additional arguments to be passed to :manpage:`git-pull(1)`.
1111 :return:
1112 Please see :meth:`fetch` method.
1113 """
1114 if refspec is None:
1115 # No argument refspec, then ensure the repo's config has a fetch refspec.
1116 self._assert_refspec()
1117 kwargs = add_progress(kwargs, self.repo.git, progress)
1119 refspec = Git._unpack_args(refspec or [])
1120 if not allow_unsafe_protocols:
1121 for ref in refspec:
1122 Git.check_unsafe_protocols(ref)
1124 if not allow_unsafe_options:
1125 Git.check_unsafe_options(options=list(kwargs.keys()), unsafe_options=self.unsafe_git_pull_options)
1127 proc = self.repo.git.pull(
1128 "--", self, refspec, with_stdout=False, as_process=True, universal_newlines=False, v=True, **kwargs
1129 )
1130 res = self._get_fetch_info_from_stderr(proc, progress, kill_after_timeout=kill_after_timeout)
1131 if hasattr(self.repo.odb, "update_cache"):
1132 self.repo.odb.update_cache()
1133 return res
1135 def push(
1136 self,
1137 refspec: Union[str, List[str], None] = None,
1138 progress: Union[RemoteProgress, "UpdateProgress", Callable[..., RemoteProgress], None] = None,
1139 kill_after_timeout: Union[None, float] = None,
1140 allow_unsafe_protocols: bool = False,
1141 allow_unsafe_options: bool = False,
1142 **kwargs: Any,
1143 ) -> PushInfoList:
1144 """Push changes from source branch in refspec to target branch in refspec.
1146 :param refspec:
1147 See :meth:`fetch` method.
1149 :param progress:
1150 Can take one of many value types:
1152 * ``None``, to discard progress information.
1153 * A function (callable) that is called with the progress information.
1154 Signature: ``progress(op_code, cur_count, max_count=None, message='')``.
1155 See :meth:`RemoteProgress.update <git.util.RemoteProgress.update>` for a
1156 description of all arguments given to the function.
1157 * An instance of a class derived from :class:`~git.util.RemoteProgress` that
1158 overrides the
1159 :meth:`RemoteProgress.update <git.util.RemoteProgress.update>` method.
1161 :note:
1162 No further progress information is returned after push returns.
1164 :param kill_after_timeout:
1165 To specify a timeout in seconds for the git command, after which the process
1166 should be killed. It is set to ``None`` by default.
1168 :param allow_unsafe_protocols:
1169 Allow unsafe protocols to be used, like ``ext``.
1171 :param allow_unsafe_options:
1172 Allow unsafe options to be used, like ``--receive-pack``.
1174 :param kwargs:
1175 Additional arguments to be passed to :manpage:`git-push(1)`.
1177 :return:
1178 A :class:`PushInfoList` object, where each list member represents an
1179 individual head which had been updated on the remote side.
1181 If the push contains rejected heads, these will have the
1182 :const:`PushInfo.ERROR` bit set in their flags.
1184 If the operation fails completely, the length of the returned
1185 :class:`PushInfoList` will be 0.
1187 Call :meth:`~PushInfoList.raise_if_error` on the returned object to raise on
1188 any failure.
1189 """
1190 kwargs = add_progress(kwargs, self.repo.git, progress)
1192 refspec = Git._unpack_args(refspec or [])
1193 if not allow_unsafe_protocols:
1194 for ref in refspec:
1195 Git.check_unsafe_protocols(ref)
1197 if not allow_unsafe_options:
1198 Git.check_unsafe_options(options=list(kwargs.keys()), unsafe_options=self.unsafe_git_push_options)
1200 proc = self.repo.git.push(
1201 "--",
1202 self,
1203 refspec,
1204 porcelain=True,
1205 as_process=True,
1206 universal_newlines=True,
1207 kill_after_timeout=kill_after_timeout,
1208 **kwargs,
1209 )
1210 return self._get_push_info(proc, progress, kill_after_timeout=kill_after_timeout)
1212 @property
1213 def config_reader(self) -> SectionConstraint[GitConfigParser]:
1214 """
1215 :return:
1216 :class:`~git.config.GitConfigParser` compatible object able to read options
1217 for only our remote. Hence you may simply type ``config.get("pushurl")`` to
1218 obtain the information.
1219 """
1220 return self._config_reader
1222 def _clear_cache(self) -> None:
1223 try:
1224 del self._config_reader
1225 except AttributeError:
1226 pass
1227 # END handle exception
1229 @property
1230 def config_writer(self) -> SectionConstraint:
1231 """
1232 :return:
1233 :class:`~git.config.GitConfigParser`-compatible object able to write options
1234 for this remote.
1236 :note:
1237 You can only own one writer at a time - delete it to release the
1238 configuration file and make it usable by others.
1240 To assure consistent results, you should only query options through the
1241 writer. Once you are done writing, you are free to use the config reader
1242 once again.
1243 """
1244 writer = self.repo.config_writer()
1246 # Clear our cache to ensure we re-read the possibly changed configuration.
1247 self._clear_cache()
1248 return SectionConstraint(writer, self._config_section_name())