▼Net:   Networking Libraries
On this page:
git-checkout
current-git-username
current-git-password
exn:  fail:  git
  top  contents    up   

22 Git Repository Checkout🔗ℹ

 (require net/git-checkout) package: base
The net/git-checkout library provides support for extracting a directory tree from a Git repository that is hosted by a server that implements the git:// protocol or its layering over HTTP(S). The net/git-checkout library does not rely on external binaries (such as a git client) or Git-specific native libraries (such as "libgit").

When run as a program, net/git-checkout accepts command-line arguments to drive the checkout. Use
  racket -l- net/git-checkout -h
for information on command-line arguments and flags.

procedure

(git-checkout hostname 
  repository 
  #:dest-dir dest-dir 
  [#:ref ref 
  #:initial-search-ref initial-search-ref 
  #:transport transport 
  #:depth depth 
  #:status-printf status-printf 
  #:initial-error initial-error 
  #:tmp-dir tmp-dir 
  #:clean-tmp-dir? clean-tmp-dir? 
  #:verify-server? verify-server? 
  #:port port 
  #:strict-links? strict-links? 
  #:username username 
  #:password password]) 
 → string?
  hostname : string?
  repository : string?
  dest-dir : (or/c path-string? #f)
  ref : (or/c string? 'head) = 'head
  initial-search-ref : string? = "master"
  transport : (or/c 'git 'http 'https) = 'git
  depth : (or/c #f exact-positive-integer?) = 1
  status-printf : (string? any/c ... . -> . void?)
   = 
(lambda args
  (apply printf args)
  (flush-output))
  initial-error : (or #f (-> any)) = #f
  tmp-dir : (or/c #f path-string?) = #f
  clean-tmp-dir? : any/c = (not tmp-dir)
  verify-server? : any/c = #t
  port : (or/c #f (integer-in 1 65535)) = 
(case transport
  [(git) 9418]
  [(http) 80]
  [(https) 443])
  strict-links? : any/c = #f
  username : (or/c string? #f) = (current-git-username)
  password : (or/c string? #f) = (current-git-password)
Contacts the server at hostname and port (where #f is replaced by the default) to download the repository whose name on the server is repository (normally ending in ".git"). The tree within the repository that is identified by ref is extracted to dest-dir, and it returns a string containing a commit ID corresponding to ref. The ref argument can be a string for a branch, tag, commit ID, or tree ID, or it can be 'head to refer to the default branch as reported by the server.

If transport is 'git, then the server is contacted using Git’s native transport. If transport is 'http or 'https, then the server is contacted using HTTP(S). In the case of 'https, the server’s identity is verified unless verify-server? is false or the GIT_SSL_NO_VERIFY environment variable is set.

If dest-dir is #f, then the result is an ID determined for ref from just the server’s report of the available branches and tags, or ref itself if it does not match a branch or tag name and looks like an ID.

A local clone of the repository is not preserved, but is instead discarded after the tree is extracted to dest-dir. If dest-dir does not exist, it is created. If dest-dir does exist, its existing content is left in place except as replaced by content from the Git repository.

If ref identifies a branch or tag by name, through 'head, or by its commit ID, then the git:// protocol allows git-checkout to download only the commits and objects relevant to the branch or tag. Furthermore, the default depth argument allows git-checkout to obtain only the latest commit and its objects, instead of the entire history of the branch or commit. If ref is any other commit ID or tree ID, then the entire repository may have to be downloaded, including all branches; however, commits in the branch or tag named by initial-search-ref will be checked, first.

Status information is reported via status-printf. The same information is always logged with the name 'git-checkout at the 'info level.

If initial-error is not #f, then it is called (to raise an exception or otherwise escape) if initial communication with the server fails to match the expected protocol—perhaps indicating that the server does not provide a Git repository at the given address. If initial-error is #f or returns when called, an exception is raised.

If tmp-dir is not #f, then it is used to store a temporary clone of the repository, and the files are preserved unless clean-tmp-dir? is true. The clone does not currently match the shape that is recognized by other tools, such as git, and so a preserved temporary directory is useful mainly for debugging.

If strict-links? is true, then the checkout fails with an error if it would produce a symbolic link that refers to an absolute path or to a relative path that contains up-directory elements.

If both username and password are non-#f and transport is 'http or 'https, then the provided credentials are passed to the remote server using HTTP Basic Authentication.

Added in version 6.1.1.1 of package base.
Changed in version 6.2.900.17: Added the strict-links? argument.
Changed in version 6.3: Added the initial-error argument.
Changed in version 6.6.0.5: Added the username and password arguments.
Changed in version 6.6.0.5: Changed to raise exn:fail:git exceptions instead of exn:fail.
Changed in version 8.0.0.8: Added support for ref as 'head and made 'head the default.
Changed in version 8.2.0.5: Added the initial-search-ref argument.

parameter

(current-git-username) → (or/c string? #f)

(current-git-username username) → void?
  username : (or/c string? #f)

parameter

(current-git-password) → (or/c string? #f)

(current-git-password password) → void?
  password : (or/c string? #f)
Parameters used by git-checkout as the default values of the username and password arguments to control authentication with the remote server.

Added in version 6.6.0.5 of package base.

struct

(struct exn:fail:git exn:fail ()
    #:extra-constructor-name make-exn:fail:git
    #:transparent)
Raised by git-checkout due to errors parsing or communicating with the git protocol.

Added in version 6.6.0.5 of package base.

  top  contents    up