From c00a0ca7309749fd34efd68816da9b897881e7e8 Mon Sep 17 00:00:00 2001 From: Tom Willemse Date: Fri, 31 May 2013 23:41:16 +0200 Subject: [PATCH] Add some docstrings --- gitto/config.scm | 37 +++++++++++++++++++++++++++++++++++++ gitto/git.scm | 22 +++++++++++++++++----- gitto/main.scm | 19 +++++++++++++++++++ 3 files changed, 73 insertions(+), 5 deletions(-) diff --git a/gitto/config.scm b/gitto/config.scm index 5459d84..f0e1635 100644 --- a/gitto/config.scm +++ b/gitto/config.scm @@ -32,6 +32,7 @@ (define hook-alist '()) (define (install-hooks repo-location) + "Install each hook in `hook-alist' into REPO-LOCATION." (for-each (lambda (hook) (let ((new-name (string-append repo-location "/.git/hooks/" @@ -41,6 +42,10 @@ hook-alist)) (define (merge-config repo-name x y) + "Merge configuration X with configuration Y. + +The values in configuration Y will have `%a' substituted with +REPO-NAME." (let ((lst (if x (list-copy x) '()))) (for-each (lambda (s) @@ -52,11 +57,18 @@ lst)) (define (merge-setting repo-name lst var val) + "Merge VAL into LST under VAR, substituting `%a' with REPO-NAME. + +In case val is a list, all values in it have `%a' substituted with +REPO-NAME." (if (list? val) (assoc-set! lst var (map (lambda (v) (format #f v repo-name)) val)) (assoc-set! lst var (format #f val repo-name)))) (define (merge-settings repo-name x y) + "Merge the settings in X with those in Y. + +During merging values in Y will have `%a' substituted with REPO-NAME." (let ((lst (if x (list-copy x) '()))) (for-each (lambda (v) @@ -65,11 +77,22 @@ lst)) (define (split-setting line) + "Split LINE into a cons cell. + +LINE should be a string which looks like `key=value'. The result is a +cons cell with `(key . value)'." (let ((idx (string-index line #\=))) (cons (string-trim-both (substring line 0 idx)) (string-trim-both (substring line (1+ idx)))))) (define (read-setting settings line) + "Read and put the setting in LINE into SETTINGS. + +LINE should be a string which looks like `key=value'. The result is +SETTINGS with either the setting in LINE added to it, the current +value of the variable specified in LINE overwritten with the value in +LINE or the value in LINE appended to the existing variable in +SETTINGS." (let* ((new-setting (split-setting line)) (var (car new-setting)) (val (cdr new-setting)) (current-value (assoc-ref settings var))) @@ -80,6 +103,10 @@ (assoc-set! settings var val)))) (define (read-config repo-location) + "Read the configuration for the git repository at REPO-LOCATION. + +This procedure returns an alist of `(SECTION-TITLE . SETTINGS)' cells +where SETTINGS is an alist of `(VARIABLE . VALUE)' cells." (let ((port (open-input-file (string-append repo-location "/.git/config"))) (config '()) @@ -104,10 +131,20 @@ (thunk)))) (define (write-section section) + "Output SECTION as a git config section. + +This prints SECTION's car as a section header and prints all the +settings in SECTION's cdr." (format #t "[~a]~%" (car section)) (for-each write-setting (cdr section))) (define (write-setting setting) + "Write SETTING to `standard-output'. + +SETTING should be a cons cell or a proper list. In the case of it +being a proper list a key=value line will be printed for each item in +the cdr of SETTING. In case of a cons cell where the cdr isn't a list +just one line will be printed." (let ((value (cdr setting))) (if (list? value) (map (lambda (v) diff --git a/gitto/git.scm b/gitto/git.scm index 41aca7e..425e26e 100644 --- a/gitto/git.scm +++ b/gitto/git.scm @@ -62,21 +62,27 @@ (force (slot-ref branch 'updated))) (define (git-branches dir) + "Call git-branch and parse its output." (let ((pipe (start-git dir "branch"))) (map (lambda (b) (string-trim-both b (char-set #\* #\space))) (string-split (string-trim-right (read-string pipe)) #\newline)))) (define (git-clean? dir) - "Check whether a repository is clean, meaning there are no changes -to the tracked files. Utracked files will not register." + "Check whether a repository is clean. + +Clean means there are no changes to the tracked files. Untracked files +will not register." (let* ((pipe (start-git dir "status -suno")) (clean? (eof-object? (read-delimited "" pipe)))) (close-pipe pipe) clean?)) (define (git-dir? dir) - "Check whether or not DIR/.git exists." + "Check whether or not DIR is a git repository. + +DIR will be considered a git repository if it has a `.git' +sub-directory." (let ((dir (string-append dir "/.git"))) (if (file-exists? dir) (let ((dirstat (stat dir))) @@ -84,7 +90,7 @@ to the tracked files. Utracked files will not register." #f))) (define (git-last-update dir branch) - "Check when the last update upstream was." + "Check when the last update in DIR of upstream for BRANCH was." (let* ((pipe (start-git dir (format #f "log -1 --format=%ar ~a@{u}" branch))) (relative-last-update (read-line pipe))) @@ -134,11 +140,17 @@ to the tracked files. Utracked files will not register." (branch-name branch) (branch-pushable branch) (branch-pullable branch) (branch-updated branch))) +(define (repo-state-description repo) + "Return the state of REPO as either clean or dirty. + +REPO should be of type `' and the result is a string." + (if (repo-clean? repo) "clean" "dirty")) + (define-method (print (repo )) (if (file-exists? (repo-location repo)) (begin (format #t "~a: Worktree is ~a~%" (repo-name repo) - (if (repo-clean? repo) "clean" "dirty")) + (repo-state-description repo)) (for-each print (repo-branches repo)) (newline)) (format #t "~a:~15tnot found at ~s\n" diff --git a/gitto/main.scm b/gitto/main.scm index 7cb98a9..0686f76 100644 --- a/gitto/main.scm +++ b/gitto/main.scm @@ -32,6 +32,11 @@ (define config-exclusion-list '()) (define (storage-dir xdg-env fallback) + "Get the location where gitto stores information. + +XDG-ENV specifies which XDG environment variable should be looked at +and FALLBACK specifies the directory to use if XDG-ENV has not been +set in the current environment." (let ((xdg (getenv xdg-env))) (string-append (or xdg (getenv "HOME")) (if xdg "" fallback) "/gitto"))) @@ -168,9 +173,19 @@ gitto [command [arguments ...]] (set! command-list (append command-list `(("purge" . ,purge)))) (define (show-global-config) + "Show the template specified in `global-config'." (write-config global-config)) (define (show-config . args) + "Do something with the config module. + +If ARGS is an empty list, show each repository's current +configuration. If the car of ARGS is `global' show the template +specified in the user's init file. If the car of ARGS is `update' +merge the specified template and each repository's configuration, +excluding the repositories in `config-exclusion-list'. If the car of +ARGS is `hooks' install configured hooks in each repository, excluding +repositories in `config-exclusion-list'." (cond ((eq? args '()) (for-each (lambda (repo) @@ -190,6 +205,9 @@ gitto [command [arguments ...]] (set! command-list (append command-list `(("config" . ,show-config)))) (define (update-repo-config repo) + "Merge the configured configuration with REPO's configuration. + +Don't do anything if REPO has been added to `config-exclusion-list'." (unless (member (repo-name repo) config-exclusion-list) (write-config (merge-config (repo-name repo) @@ -198,6 +216,7 @@ gitto [command [arguments ...]] (string-append (repo-location repo) "/.git/config")))) (define (update-config) + "Merge the configured configuration with all repositories." (for-each update-repo-config repositories)) (define (main args)