├── README.md ├── README ├── KaleidoscopeLogo-Black@2x.jpg └── screen │ ├── cat@2x.jpg │ ├── integration@2x.jpg │ └── search@2x.jpg ├── convert2text.sh └── man-diff.sh /README.md: -------------------------------------------------------------------------------- 1 | Kaleidoscope Logo 2 | 3 | # What's up, man(1)? 4 | 5 |
6 | 7 | ### Find differences in man pages starting with macOS Big Sur 11.6. 8 | 9 | 10 | 11 | ## Introduction 12 | 13 | The other day we found a helpful command line tool option, only to discover later that the option was only available in macOS Monterey. Since we also need to target Big Sur, this would not be an option for us. So we created something to help us overcome similar issues in the future: a way to compare man pages between macOS system versions. 14 | 15 | Read the full blog post here: [What’s new in the macOS Monterey command line](https://blog.kaleidoscope.app/2021/10/25/whats-new-in-the-macos-monterey-command-line/) 16 | 17 | ## Usage 18 | 19 | Clone repository: 20 | ``` 21 | git clone https://github.com/kaleidoscope-app/man-diff.git 22 | ``` 23 | 24 | Execute the included man-diff shell script: 25 | 26 | ``` 27 | ./man-diff.sh -all 28 | ``` 29 | 30 | This will open a document like the screenshot above in Kaleidoscope. 31 | 32 | 33 | 34 | Use the search field in the lower left to filter command names. The Modified, Added and Deleted buttons can be used to exlude that kind of change. 35 | 36 | Or quickly lookup a single man page: 37 | 38 | ``` 39 | ./man-diff.sh plutil 40 | ``` 41 | 42 | ## Changelog 43 | 44 | Jan 24, 2024: 45 | * No changes in macOS 14.3 46 | 47 | Dec 12, 2023: 48 | * Added macOS 14.2: 49 | ```git difftool changeset/macOS14.1..changeset/macOS14.2``` 50 | * No changes in macOS 14.1.2 51 | 52 | Nov 9, 2023: 53 | * No changes in macOS 14.1.1 54 | * Added macOS 14.1: 55 | ```git difftool changeset/macOS14.0..changeset/macOS14.1``` 56 | 57 | Sep 26, 2023: 58 | * Added macOS 14.0: 59 | ```git difftool changeset/macOS13.5..changeset/macOS14.0``` 60 | * No changes in macOS 13.5.1 61 | * No changes in macOS 13.5.2 62 | 63 | Jul 24, 2023: 64 | * Added macOS 13.5: 65 | ```git difftool changeset/macOS13.4..changeset/macOS13.5``` 66 | 67 | May 19, 2023: 68 | * Added macOS 13.4: 69 | ```git difftool changeset/macOS13.3..changeset/macOS13.4``` 70 | 71 | Mar 28, 2023: 72 | * Added macOS 13.3: 73 | ```git difftool changeset/macOS13.2.1..changeset/macOS13.3``` 74 | * No changes in macOS 13.2.1 75 | 76 | Jan 24, 2023: 77 | * Added macOS 13.2: 78 | ```git difftool changeset/macOS13.1..changeset/macOS13.2``` 79 | 80 | Jan 12, 2023: 81 | * Added macOS 13.1: 82 | ```git difftool changeset/macOS13.0..changeset/macOS13.1``` 83 | * No changes in macOS 13.0.1 84 | 85 | Oct 24, 2022: 86 | 87 | * Added macOS 13.0 which includes 611 changed files of which 331 are perl related version changes: 88 | * We post processed the changeset and grouped perl related changes: 89 | ```git difftool changeset/macOS12.6-post-processed..changeset/macOS13.0``` 90 | * To see all changes you can do so with: 91 | ```git difftool changeset/macOS12.6..changeset/macOS13.0``` 92 | 93 | Oct 20, 2022: 94 | 95 | * Added macOS 12.6: 96 | ```git difftool changeset/macOS12.5..changeset/macOS12.6``` 97 | 98 | Aug 10, 2022: 99 | 100 | * Added macOS 12.5: 101 | ```git difftool changeset/macOS12.4..changeset/macOS12.5``` 102 | 103 | May 16, 2022: 104 | 105 | * Added macOS 12.4: 106 | ```git difftool changeset/macOS12.3..changeset/macOS12.4``` 107 | 108 | Mar 15, 2022: 109 | 110 | * Added macOS 12.3: 111 | * We post processed the changeset and grouped buildins changes: 112 | ```git difftool changeset/macOS12.2-post-processed..changeset/macOS12.3``` 113 | * To see all changes you can do so with: 114 | ```git difftool changeset/macOS12.2..changeset/macOS12.3``` 115 | 116 | Jan 29, 2021: 117 | 118 | * Added macOS 12.2: 119 | ```git difftool changeset/macOS12.1..changeset/macOS12.2``` 120 | 121 | Dec 14, 2021: 122 | 123 | * Added macOS 12.1: 124 | ```git difftool changeset/macOS12..changeset/macOS12.1``` 125 | * Removed man page footer to simplify diff 126 | 127 | ## Prerequisites 128 | 129 | git and diff tool of your choice. Of course we recommend Kaleidoscope. 130 | 131 | * Install [Kaleidoscope for Mac](https://kaleidoscope.app) 132 | * In Kaleidoscope, select Kaleidoscope > Integration from the menu 133 | * If needed, click the Install buttons for ksdiff and Git 134 | 135 | 136 | 137 | ## Feedback 138 | 139 | We’d [love to hear](mailto:support@kaleidoscope.app?Subject=man-diff%20Feedback) if you find this useful or have ideas for improvements. 140 | 141 | ### Notes 142 | 143 | We post processed the default changeset so it is easier to digest, ignoring changes to Perl (spanning 494 files), macOS name changes and text reformatting. 144 | 145 | If you want to see all changes you can do so with: 146 | 147 | ``` 148 | git difftool macOS/11.6..macOS/12.0.1 149 | ``` 150 | -------------------------------------------------------------------------------- /README/KaleidoscopeLogo-Black@2x.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kaleidoscope-app/man-diff/c16e02ca95ac990110aafdc63c2b6399ee0c006d/README/KaleidoscopeLogo-Black@2x.jpg -------------------------------------------------------------------------------- /README/screen/cat@2x.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kaleidoscope-app/man-diff/c16e02ca95ac990110aafdc63c2b6399ee0c006d/README/screen/cat@2x.jpg -------------------------------------------------------------------------------- /README/screen/integration@2x.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kaleidoscope-app/man-diff/c16e02ca95ac990110aafdc63c2b6399ee0c006d/README/screen/integration@2x.jpg -------------------------------------------------------------------------------- /README/screen/search@2x.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kaleidoscope-app/man-diff/c16e02ca95ac990110aafdc63c2b6399ee0c006d/README/screen/search@2x.jpg -------------------------------------------------------------------------------- /convert2text.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | 4 | if [[ "$#" -lt "1" ]]; then 5 | echo 6 | echo usage: $0 src dst 7 | echo 8 | echo Prepare src folder like this: 9 | echo mkdir -p src/root/usr/share 10 | echo mkdir -p src/System/Library/Filesystems/acfs.fs/Contents 11 | echo cp -r /usr/share/man src/root/usr/share 12 | echo cp -r /System/Library/Filesystems/acfs.fs/Contents/man src/System/Library/Filesystems/acfs.fs/Contents 13 | echo sw_vers > src/sw_vers.txt 14 | echo 15 | exit 1 16 | fi 17 | 18 | SRC=$1 19 | DST=$2 20 | 21 | if [ ! -d "$SRC" ]; then 22 | echo "$0 src directory needs to exist." 23 | exit 1 24 | fi 25 | 26 | if [ -z ${DST+x} ]; then 27 | echo "usage: $0 src dst" 28 | exit 1 29 | fi 30 | 31 | for PAGE_PATH in "$SRC"/root/usr/share/man/**/*; 32 | do 33 | PAGE_NAME=$(basename "$PAGE_PATH") 34 | PAGE_NAME=${PAGE_NAME%.*} # remove file extension 35 | PAGE_SECTION_PATH=$(dirname "$PAGE_PATH") 36 | PAGE_SECTION=$(basename "$PAGE_SECTION_PATH") 37 | case "$PAGE_SECTION" in 38 | "man1") 39 | SECTION_NR="1" 40 | SECTION_DESC="User Commands" 41 | ;; 42 | "man2") 43 | SECTION_NR="2" 44 | SECTION_DESC="System Calls" 45 | ;; 46 | "man3") 47 | SECTION_NR="3" 48 | SECTION_DESC="C Library Functions" 49 | ;; 50 | "man4") 51 | SECTION_NR="4" 52 | SECTION_DESC="Devices and Special Files" 53 | ;; 54 | "man5") 55 | SECTION_NR="5" 56 | SECTION_DESC="File Formats and Conventions" 57 | ;; 58 | "man6") 59 | SECTION_NR="6" 60 | SECTION_DESC="Games et. Al." 61 | ;; 62 | "man7") 63 | SECTION_NR="7" 64 | SECTION_DESC="Miscellanea" 65 | ;; 66 | "man8") 67 | SECTION_NR="8" 68 | SECTION_DESC="System Administration" 69 | ;; 70 | *) 71 | SECTION_NR=${PAGE_SECTION:3} # manxx -> xx 72 | SECTION_DESC="" 73 | ;; 74 | esac 75 | FANCY_DIR_PATH="$DST/man/$SECTION_NR/$SECTION_DESC" 76 | mkdir -p "$FANCY_DIR_PATH" 77 | #/usr/bin/man -P /bin/cat "$PAGE_PATH" > "$DST/$PAGE_PATH.txt" 78 | export MANWIDTH=80 79 | /usr/bin/man -c "$PAGE_PATH" | col -bx \ 80 | | awk '/^mandoc: / { print $0 > "/dev/stderr"; next } { print $0 }' \ 81 | | sed '$d' \ 82 | > "$FANCY_DIR_PATH/$PAGE_NAME" 83 | done 84 | 85 | cp "$SRC/sw_vers.txt" "$DST/info.txt" 86 | 87 | -------------------------------------------------------------------------------- /man-diff.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | if [[ ! -d .git ]]; then 4 | echo "$0: require git repository" >&2 5 | echo "$0: git clone https://github.com/kaleidoscope-app/man-diff.git ." >&2 6 | exit 1 7 | fi 8 | 9 | if [[ "$#" -lt "1" ]]; then 10 | echo "usage: $0 -all" >&2 11 | echo "usage: $0 [section] name" >&2 12 | exit 1 13 | fi 14 | 15 | if [[ "$1" == "-all" ]]; then 16 | git difftool "changeset/macOS11" "changeset/macOS12" 17 | exit $? 18 | fi 19 | 20 | function resolve_section() { 21 | SECTION_DESC="" 22 | case "$1" in 23 | "man1") 24 | echo "User Commands" 25 | ;; 26 | "man2") 27 | echo "System Calls" 28 | ;; 29 | "man3") 30 | echo "C Library Functions" 31 | ;; 32 | "man4") 33 | echo "Devices and Special Files" 34 | ;; 35 | "man5") 36 | echo "File Formats and Conventions" 37 | ;; 38 | "man6") 39 | echo "Games et. Al." 40 | ;; 41 | "man7") 42 | echo "Miscellanea" 43 | ;; 44 | "man8") 45 | echo "System Administration" 46 | ;; 47 | *) 48 | echo "" 49 | ;; 50 | esac 51 | } 52 | 53 | function file_exists() { 54 | git cat-file -e "$1:$MANPAGE_PATH" 2>/dev/null 55 | return $? 56 | } 57 | 58 | function compare_man_page() { 59 | BRANCH_A="macOS/11.6" 60 | BRANCH_B="macOS/12.0.1" 61 | SECTION=$1 62 | NAME=$2 63 | SECTION_DESC=$(resolve_section "man$SECTION") 64 | ESC_SECTION_DESC=$(printf '%q' "$SECTION_DESC") #escapes filenames. 65 | MANPAGE_PATH="" 66 | if [[ "$SECTION_DESC" != "" ]]; then 67 | MANPAGE_PATH="man/$SECTION/$SECTION_DESC/$NAME" 68 | else 69 | MANPAGE_PATH="man/$SECTION/$NAME" 70 | fi 71 | 72 | if ! file_exists "$BRANCH_A" && ! file_exists "$BRANCH_B" 73 | then 74 | echo "$0: $MANPAGE_PATH: No such file" 75 | exit 1 76 | fi 77 | 78 | if ! file_exists "$BRANCH_A" && file_exists "$BRANCH_B" 79 | then 80 | echo "$0: $MANPAGE_PATH: No such file in $BRANCH_A" 81 | exit 2 82 | fi 83 | if file_exists "$BRANCH_A" && ! file_exists "$BRANCH_B" 84 | then 85 | echo "$0: $MANPAGE_PATH: No such file in $BRANCH_B" 86 | exit 2 87 | fi 88 | 89 | if git difftool --exit-code "$BRANCH_A" "$BRANCH_B" -- "$MANPAGE_PATH" 90 | then 91 | echo "$0: No changes in $MANPAGE_PATH" 92 | exit 3 93 | fi 94 | exit 0 95 | } 96 | 97 | if [[ $# -eq 1 ]]; then 98 | for i in "1" "2" "2" "3" "4" "5" "6" "7" "8" "9" "n" 99 | do 100 | STDOUT=$(compare_man_page "$i" "$1") 101 | EXIT_STATUS=$? 102 | 103 | if [[ "$EXIT_STATUS" == "0" ]]; then 104 | exit 0 105 | fi 106 | 107 | if [[ "$EXIT_STATUS" == "2" ]] || [[ "$EXIT_STATUS" == "3" ]] ; then 108 | echo $STDOUT 109 | exit $EXIT_STATUS 110 | fi 111 | 112 | if [[ "$i" == "n" ]] && [ $EXIT_STATUS -ne 0 ]; then 113 | echo "$0: No manual entry for $1" 114 | exit 1 115 | fi 116 | done 117 | fi 118 | 119 | if [[ $# -eq 2 ]]; then 120 | compare_man_page "$1" "$2" 121 | fi 122 | --------------------------------------------------------------------------------