Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/git/remote.py: 25%
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 # `rm` is an alias.
832 rm = remove
834 def rename(self, new_name: str) -> "Remote":
835 """Rename self to the given `new_name`.
837 :return:
838 self
839 """
840 if self.name == new_name:
841 return self
843 self.repo.git.remote("rename", self.name, new_name)
844 self.name = new_name
845 self._clear_cache()
847 return self
849 def update(self, **kwargs: Any) -> "Remote":
850 """Fetch all changes for this remote, including new branches which will be
851 forced in (in case your local remote branch is not part the new remote branch's
852 ancestry anymore).
854 :param kwargs:
855 Additional arguments passed to ``git remote update``.
857 :return:
858 self
859 """
860 scmd = "update"
861 kwargs["insert_kwargs_after"] = scmd
862 self.repo.git.remote(scmd, self.name, **kwargs)
863 return self
865 def _get_fetch_info_from_stderr(
866 self,
867 proc: "Git.AutoInterrupt",
868 progress: Union[Callable[..., Any], RemoteProgress, None],
869 kill_after_timeout: Union[None, float] = None,
870 ) -> IterableList["FetchInfo"]:
871 progress = to_progress_instance(progress)
873 # Skip first line as it is some remote info we are not interested in.
874 output: IterableList["FetchInfo"] = IterableList("name")
876 # Lines which are no progress are fetch info lines.
877 # This also waits for the command to finish.
878 # Skip some progress lines that don't provide relevant information.
879 fetch_info_lines = []
880 # Basically we want all fetch info lines which appear to be in regular form, and
881 # thus have a command character. Everything else we ignore.
882 cmds = set(FetchInfo._flag_map.keys())
884 progress_handler = progress.new_message_handler()
885 handle_process_output(
886 proc,
887 None,
888 progress_handler,
889 finalizer=None,
890 decode_streams=True,
891 kill_after_timeout=kill_after_timeout,
892 )
894 stderr_text = progress.error_lines and "\n".join(progress.error_lines) or ""
895 proc.wait(stderr=stderr_text)
896 if stderr_text:
897 _logger.warning("Error lines received while fetching: %s", stderr_text)
899 for line in progress.other_lines:
900 line = force_text(line)
901 for cmd in cmds:
902 if len(line) > 1 and line[0] == " " and line[1] == cmd:
903 fetch_info_lines.append(line)
904 continue
906 # Read head information.
907 fetch_head = SymbolicReference(self.repo, "FETCH_HEAD")
908 with open(fetch_head.abspath, "rb") as fp:
909 fetch_head_info = [line.decode(defenc) for line in fp.readlines()]
911 l_fil = len(fetch_info_lines)
912 l_fhi = len(fetch_head_info)
913 if l_fil != l_fhi:
914 msg = "Fetch head lines do not match lines provided via progress information\n"
915 msg += "length of progress lines %i should be equal to lines in FETCH_HEAD file %i\n"
916 msg += "Will ignore extra progress lines or fetch head lines."
917 msg %= (l_fil, l_fhi)
918 _logger.debug(msg)
919 _logger.debug(b"info lines: " + str(fetch_info_lines).encode("UTF-8"))
920 _logger.debug(b"head info: " + str(fetch_head_info).encode("UTF-8"))
921 if l_fil < l_fhi:
922 fetch_head_info = fetch_head_info[:l_fil]
923 else:
924 fetch_info_lines = fetch_info_lines[:l_fhi]
925 # END truncate correct list
926 # END sanity check + sanitization
928 for err_line, fetch_line in zip(fetch_info_lines, fetch_head_info):
929 try:
930 output.append(FetchInfo._from_line(self.repo, err_line, fetch_line))
931 except ValueError as exc:
932 _logger.debug("Caught error while parsing line: %s", exc)
933 _logger.warning("Git informed while fetching: %s", err_line.strip())
934 return output
936 def _get_push_info(
937 self,
938 proc: "Git.AutoInterrupt",
939 progress: Union[Callable[..., Any], RemoteProgress, None],
940 kill_after_timeout: Union[None, float] = None,
941 ) -> PushInfoList:
942 progress = to_progress_instance(progress)
944 # Read progress information from stderr.
945 # We hope stdout can hold all the data, it should...
946 # Read the lines manually as it will use carriage returns between the messages
947 # to override the previous one. This is why we read the bytes manually.
948 progress_handler = progress.new_message_handler()
949 output: PushInfoList = PushInfoList()
951 def stdout_handler(line: str) -> None:
952 try:
953 output.append(PushInfo._from_line(self, line))
954 except ValueError:
955 # If an error happens, additional info is given which we parse below.
956 pass
958 handle_process_output(
959 proc,
960 stdout_handler,
961 progress_handler,
962 finalizer=None,
963 decode_streams=False,
964 kill_after_timeout=kill_after_timeout,
965 )
966 stderr_text = progress.error_lines and "\n".join(progress.error_lines) or ""
967 try:
968 proc.wait(stderr=stderr_text)
969 except Exception as e:
970 # This is different than fetch (which fails if there is any stderr
971 # even if there is an output).
972 if not output:
973 raise
974 elif stderr_text:
975 _logger.warning("Error lines received while fetching: %s", stderr_text)
976 output.error = e
978 return output
980 def _assert_refspec(self) -> None:
981 """Turns out we can't deal with remotes if the refspec is missing."""
982 config = self.config_reader
983 unset = "placeholder"
984 try:
985 if config.get_value("fetch", default=unset) is unset:
986 msg = "Remote '%s' has no refspec set.\n"
987 msg += "You can set it as follows:"
988 msg += " 'git config --add \"remote.%s.fetch +refs/heads/*:refs/heads/*\"'."
989 raise AssertionError(msg % (self.name, self.name))
990 finally:
991 config.release()
993 def fetch(
994 self,
995 refspec: Union[str, List[str], None] = None,
996 progress: Union[RemoteProgress, None, "UpdateProgress"] = None,
997 verbose: bool = True,
998 kill_after_timeout: Union[None, float] = None,
999 allow_unsafe_protocols: bool = False,
1000 allow_unsafe_options: bool = False,
1001 **kwargs: Any,
1002 ) -> IterableList[FetchInfo]:
1003 """Fetch the latest changes for this remote.
1005 :param refspec:
1006 A "refspec" is used by fetch and push to describe the mapping
1007 between remote ref and local ref. They are combined with a colon in
1008 the format ``<src>:<dst>``, preceded by an optional plus sign, ``+``.
1009 For example: ``git fetch $URL refs/heads/master:refs/heads/origin`` means
1010 "grab the master branch head from the $URL and store it as my origin
1011 branch head". And ``git push $URL refs/heads/master:refs/heads/to-upstream``
1012 means "publish my master branch head as to-upstream branch at $URL".
1013 See also :manpage:`git-push(1)`.
1015 Taken from the git manual, :manpage:`gitglossary(7)`.
1017 Fetch supports multiple refspecs (as the underlying :manpage:`git-fetch(1)`
1018 does) - supplying a list rather than a string for 'refspec' will make use of
1019 this facility.
1021 :param progress:
1022 See the :meth:`push` method.
1024 :param verbose:
1025 Boolean for verbose output.
1027 :param kill_after_timeout:
1028 To specify a timeout in seconds for the git command, after which the process
1029 should be killed. It is set to ``None`` by default.
1031 :param allow_unsafe_protocols:
1032 Allow unsafe protocols to be used, like ``ext``.
1034 :param allow_unsafe_options:
1035 Allow unsafe options to be used, like ``--upload-pack``.
1037 :param kwargs:
1038 Additional arguments to be passed to :manpage:`git-fetch(1)`.
1040 :return:
1041 IterableList(FetchInfo, ...) list of :class:`FetchInfo` instances providing
1042 detailed information about the fetch results
1044 :note:
1045 As fetch does not provide progress information to non-ttys, we cannot make
1046 it available here unfortunately as in the :meth:`push` method.
1047 """
1048 if refspec is None:
1049 # No argument refspec, then ensure the repo's config has a fetch refspec.
1050 self._assert_refspec()
1052 kwargs = add_progress(kwargs, self.repo.git, progress)
1053 if isinstance(refspec, list):
1054 args: Sequence[Optional[str]] = refspec
1055 else:
1056 args = [refspec]
1058 if not allow_unsafe_protocols:
1059 for ref in args:
1060 if ref:
1061 Git.check_unsafe_protocols(ref)
1063 if not allow_unsafe_options:
1064 Git.check_unsafe_options(options=list(kwargs.keys()), unsafe_options=self.unsafe_git_fetch_options)
1066 proc = self.repo.git.fetch(
1067 "--", self, *args, as_process=True, with_stdout=False, universal_newlines=False, v=verbose, **kwargs
1068 )
1069 res = self._get_fetch_info_from_stderr(proc, progress, kill_after_timeout=kill_after_timeout)
1070 if hasattr(self.repo.odb, "update_cache"):
1071 self.repo.odb.update_cache()
1072 return res
1074 def pull(
1075 self,
1076 refspec: Union[str, List[str], None] = None,
1077 progress: Union[RemoteProgress, "UpdateProgress", None] = None,
1078 kill_after_timeout: Union[None, float] = None,
1079 allow_unsafe_protocols: bool = False,
1080 allow_unsafe_options: bool = False,
1081 **kwargs: Any,
1082 ) -> IterableList[FetchInfo]:
1083 """Pull changes from the given branch, being the same as a fetch followed by a
1084 merge of branch with your local branch.
1086 :param refspec:
1087 See :meth:`fetch` method.
1089 :param progress:
1090 See :meth:`push` method.
1092 :param kill_after_timeout:
1093 See :meth:`fetch` method.
1095 :param allow_unsafe_protocols:
1096 Allow unsafe protocols to be used, like ``ext``.
1098 :param allow_unsafe_options:
1099 Allow unsafe options to be used, like ``--upload-pack``.
1101 :param kwargs:
1102 Additional arguments to be passed to :manpage:`git-pull(1)`.
1104 :return:
1105 Please see :meth:`fetch` method.
1106 """
1107 if refspec is None:
1108 # No argument refspec, then ensure the repo's config has a fetch refspec.
1109 self._assert_refspec()
1110 kwargs = add_progress(kwargs, self.repo.git, progress)
1112 refspec = Git._unpack_args(refspec or [])
1113 if not allow_unsafe_protocols:
1114 for ref in refspec:
1115 Git.check_unsafe_protocols(ref)
1117 if not allow_unsafe_options:
1118 Git.check_unsafe_options(options=list(kwargs.keys()), unsafe_options=self.unsafe_git_pull_options)
1120 proc = self.repo.git.pull(
1121 "--", self, refspec, with_stdout=False, as_process=True, universal_newlines=False, v=True, **kwargs
1122 )
1123 res = self._get_fetch_info_from_stderr(proc, progress, kill_after_timeout=kill_after_timeout)
1124 if hasattr(self.repo.odb, "update_cache"):
1125 self.repo.odb.update_cache()
1126 return res
1128 def push(
1129 self,
1130 refspec: Union[str, List[str], None] = None,
1131 progress: Union[RemoteProgress, "UpdateProgress", Callable[..., RemoteProgress], None] = None,
1132 kill_after_timeout: Union[None, float] = None,
1133 allow_unsafe_protocols: bool = False,
1134 allow_unsafe_options: bool = False,
1135 **kwargs: Any,
1136 ) -> PushInfoList:
1137 """Push changes from source branch in refspec to target branch in refspec.
1139 :param refspec:
1140 See :meth:`fetch` method.
1142 :param progress:
1143 Can take one of many value types:
1145 * ``None``, to discard progress information.
1146 * A function (callable) that is called with the progress information.
1147 Signature: ``progress(op_code, cur_count, max_count=None, message='')``.
1148 See :meth:`RemoteProgress.update <git.util.RemoteProgress.update>` for a
1149 description of all arguments given to the function.
1150 * An instance of a class derived from :class:`~git.util.RemoteProgress` that
1151 overrides the
1152 :meth:`RemoteProgress.update <git.util.RemoteProgress.update>` method.
1154 :note:
1155 No further progress information is returned after push returns.
1157 :param kill_after_timeout:
1158 To specify a timeout in seconds for the git command, after which the process
1159 should be killed. It is set to ``None`` by default.
1161 :param allow_unsafe_protocols:
1162 Allow unsafe protocols to be used, like ``ext``.
1164 :param allow_unsafe_options:
1165 Allow unsafe options to be used, like ``--receive-pack``.
1167 :param kwargs:
1168 Additional arguments to be passed to :manpage:`git-push(1)`.
1170 :return:
1171 A :class:`PushInfoList` object, where each list member represents an
1172 individual head which had been updated on the remote side.
1174 If the push contains rejected heads, these will have the
1175 :const:`PushInfo.ERROR` bit set in their flags.
1177 If the operation fails completely, the length of the returned
1178 :class:`PushInfoList` will be 0.
1180 Call :meth:`~PushInfoList.raise_if_error` on the returned object to raise on
1181 any failure.
1182 """
1183 kwargs = add_progress(kwargs, self.repo.git, progress)
1185 refspec = Git._unpack_args(refspec or [])
1186 if not allow_unsafe_protocols:
1187 for ref in refspec:
1188 Git.check_unsafe_protocols(ref)
1190 if not allow_unsafe_options:
1191 Git.check_unsafe_options(options=list(kwargs.keys()), unsafe_options=self.unsafe_git_push_options)
1193 proc = self.repo.git.push(
1194 "--",
1195 self,
1196 refspec,
1197 porcelain=True,
1198 as_process=True,
1199 universal_newlines=True,
1200 kill_after_timeout=kill_after_timeout,
1201 **kwargs,
1202 )
1203 return self._get_push_info(proc, progress, kill_after_timeout=kill_after_timeout)
1205 @property
1206 def config_reader(self) -> SectionConstraint[GitConfigParser]:
1207 """
1208 :return:
1209 :class:`~git.config.GitConfigParser` compatible object able to read options
1210 for only our remote. Hence you may simply type ``config.get("pushurl")`` to
1211 obtain the information.
1212 """
1213 return self._config_reader
1215 def _clear_cache(self) -> None:
1216 try:
1217 del self._config_reader
1218 except AttributeError:
1219 pass
1220 # END handle exception
1222 @property
1223 def config_writer(self) -> SectionConstraint:
1224 """
1225 :return:
1226 :class:`~git.config.GitConfigParser`-compatible object able to write options
1227 for this remote.
1229 :note:
1230 You can only own one writer at a time - delete it to release the
1231 configuration file and make it usable by others.
1233 To assure consistent results, you should only query options through the
1234 writer. Once you are done writing, you are free to use the config reader
1235 once again.
1236 """
1237 writer = self.repo.config_writer()
1239 # Clear our cache to ensure we re-read the possibly changed configuration.
1240 self._clear_cache()
1241 return SectionConstraint(writer, self._config_section_name())