Riga di comando

Il comando groupshelf raggruppa le finestre aperte, aggiunge ai gruppi o li scioglie ed elenca le finestre, da Terminale o da uno script. È incluso in GroupShelf 1.3.0 e versioni successive.

Installazione

Il comando fa parte di GroupShelf.app. Installarlo significa collegarlo in una cartella del tuo PATH.

Con Homebrew, installando GroupShelf il comando viene collegato automaticamente:

brew install --cask alpharium-tech/tap/groupshelf

Se hai installato GroupShelf con Homebrew prima della 1.3.0, gli aggiornamenti dall’app non aggiungono il collegamento. Esegui questo una volta:

brew reinstall --cask groupshelf

Senza Homebrew, GroupShelf mostra in Impostazioni › Riga di comando il comando che crea il collegamento, pronto da copiare. Eseguilo in Terminale; ti verrà chiesta la password del Mac. Per GroupShelf nella cartella Applicazioni, è questo:

sudo mkdir -p /usr/local/bin && sudo ln -sf '/Applications/GroupShelf.app/Contents/Helpers/groupshelf' /usr/local/bin/groupshelf

Le Impostazioni lo propongono solo quando GroupShelf è nella cartella Applicazioni ed è stato aperto da lì: un collegamento a una copia in Download smetterebbe di funzionare spostando l’app.

Una volta installato il comando, Impostazioni › Riga di comando mostra dove si trova e groupshelf version indica la versione del GroupShelf a cui appartiene.

Attivazione

I comandi che agiscono sulle finestre funzionano solo dopo che li hai consentiti: in Impostazioni › Riga di comando di GroupShelf, attiva “Consenti il controllo da riga di comando e script”. Resta disattivato finché non lo attivi. help e version funzionano in ogni caso.

Finché è attivo, le app a cui consenti di controllare GroupShelf (come la tua app di terminale) e tutto ciò che vi viene eseguito possono raggruppare finestre e leggere il titolo di ogni finestra su questa scrivania.

Autorizzazioni

La prima volta, macOS chiede se la tua app di terminale può controllare GroupShelf, e il comando attende la risposta. Se hai rifiutato, attiva GroupShelf sotto la tua app di terminale in Impostazioni di Sistema › Privacy e sicurezza › Automazione.

Visual Studio Code

La build Universal di VS Code, quella che scarica la maggior parte delle persone (versioni 1.104 e successive), non ha una voce che macOS richiede prima di chiedere questa autorizzazione. macOS rifiuterebbe senza chiedere e non elencherebbe mai GroupShelf sotto Visual Studio Code, quindi groupshelf fa comunque chiedere a macOS. Mostra questa riga, e la finestra di dialogo nomina Visual Studio Code:

groupshelf: asking macOS whether your terminal app may control GroupShelf…

Rispondi una volta e da lì in poi funziona. Se GroupShelf non compare ancora sotto Visual Studio Code in Automazione, installa la build Apple silicon o Intel di VS Code invece di quella Universal: entrambe contengono la voce. Il cask visual-studio-code di Homebrew installa la build per il chip del tuo Mac.

Indicare le finestre

Ovunque un comando accetti un <window>, scrivilo in uno di questi tre modi. Metti tra virgolette tutto ciò che contiene spazi.

Indica un’app due volte per prenderne due finestre.

Un titolo che corrisponde a più finestre è un errore, a meno che tu non aggiunga --frontmost, che prende quella più in primo piano, o --all, che le prende tutte. --all prende anche tutte le finestre di un’app indicata senza titolo.

groupshelf non apre mai un’app, quindi l’app deve essere aperta. group e add attendono fino a 30 secondi che compaia una finestra di un’app aperta, quindi funziona anche un’app aperta appena prima:

open -a Safari && open -a Terminal && groupshelf group Safari Terminal

Contano solo le finestre su questa scrivania, comprese quelle contratte. Una finestra a tutto schermo ha una scrivania tutta sua, quindi non conta.

Un percorso relativo viene letto dalla cartella attuale. Per aggiungere un titolo a un percorso, mettilo dopo .app:, come in /Applications/Safari.app:Docs.

Comandi

groupshelf help elenca i comandi e groupshelf help <command> ne spiega uno. Se GroupShelf non è aperto, un comando lo avvia in background; non apre mai le app che indichi.

Le opzioni possono stare ovunque prima di un --, con il valore dopo uno spazio o un =: --name Work o --name=Work. Metti un’app il cui nome inizia con - dopo --.

group

groupshelf group [--name <name>] [--all | --frontmost] <window> <window>...

Raggruppa le finestre in un unico insieme di pannelli, nell’ordine indicato. La prima finestra stabilisce posizione e dimensioni del gruppo, e alla fine viene mostrato il suo pannello. Una finestra già in un altro gruppo lo lascia per entrare in questo.

Servono almeno due finestre, oppure un solo <window> con --all. Se alcune non compaiono entro 30 secondi, il gruppo viene formato con le altre e il comando segnala quelle mancanti. Eseguito su un gruppo composto esattamente da quelle finestre, si limita a mettere i pannelli nell’ordine indicato.

Opzioni
--name <name>
Assegna un nome al nuovo gruppo, per trovarlo poi con --group.
--frontmost
Quando un titolo corrisponde a più finestre, prende quella più in primo piano.
--all
Prende tutte le finestre che corrispondono: tutte quelle di un’app, tutte quelle che hanno un titolo.
Esempi
groupshelf group Safari Terminal Notes Mailgroupshelf group --name Work Code:proj-a Terminal:proj-a Safariopen -a Safari && open -a Terminal && groupshelf group Safari Terminalgroupshelf group --all Terminal

add

groupshelf add [--all | --frontmost] --group <name> <window>...
groupshelf add [--all | --frontmost] <member> <window>...

Aggiunge finestre alla fine di un gruppo esistente su questa scrivania, che mantiene posizione, dimensioni e pannello mostrato. Una finestra già in un altro gruppo viene spostata. Come con group, si usano solo finestre già aperte, attendendo fino a 30 secondi.

Indica il gruppo con --group o con una delle sue finestre (<member>, scritto come un <window>). Un’app, o un titolo con --frontmost, prende una finestra che il gruppo non ha ancora, se c’è; una finestra già nel gruppo resta com’è.

Opzioni
--group <name>
Un gruppo indicato per nome, senza distinguere maiuscole: quello dato con --name o con “Assegna nome al gruppo…” facendo clic con il tasto destro sulla sua barra dei pannelli.
--frontmost
Quando un titolo corrisponde a più finestre, prende quella più in primo piano.
--all
Prende tutte le finestre che corrispondono: tutte quelle di un’app, tutte quelle che hanno un titolo.
Esempi
groupshelf add --group Work Slackgroupshelf add Code:proj-a Terminal:proj-a

detach

groupshelf detach [--all | --frontmost] <window>...

Stacca le finestre dai loro gruppi; un gruppo rimasto con una sola finestra viene sciolto. Non si apre né si attende nulla: le finestre devono essere già su questa scrivania. Una finestra che non è in alcun gruppo resta com’è.

Opzioni
--frontmost
Quando un titolo corrisponde a più finestre, prende quella più in primo piano.
--all
Prende tutte le finestre che corrispondono: tutte quelle di un’app, tutte quelle che hanno un titolo.
Esempio
groupshelf detach Slack

ungroup

groupshelf ungroup [--group <name>]... [<member>]...

Scioglie i gruppi, lasciando le finestre dove sono. Indica un gruppo con --group (ripetilo per più gruppi) o con una delle sue finestre (<member>, scritto come un <window>). Una finestra che non è in alcun gruppo viene saltata. Se uno di essi non si trova, nessun gruppo viene sciolto.

Opzioni
--group <name>
Un gruppo indicato per nome, senza distinguere maiuscole: quello dato con --name o con “Assegna nome al gruppo…” facendo clic con il tasto destro sulla sua barra dei pannelli.
Esempi
groupshelf ungroup --group Workgroupshelf ungroup Code:proj-a

list

groupshelf list

Elenca le finestre su questa scrivania che si possono raggruppare, dalla più in primo piano all’ultima, con quelle contratte in fondo. Le finestre di GroupShelf e quelle delle app escluse non compaiono. Ogni riga è una finestra, con questi campi separati da tabulazioni e senza riga di intestazione:

  1. ID finestra
  2. Nome dell’app
  3. Titolo
  4. Numero del gruppo, o vuoto
  5. Nome del gruppo, o vuoto
  6. minimized, o vuoto
groupshelf list4211	Safari	GroupShelf — Command line	1	Work	4198	Terminal	proj-a — zsh	1	Work	4305	Mail	Inbox			3977	Notes	Shopping			minimized

Una tabulazione o un a capo in un titolo diventa uno spazio, così i campi restano sempre allineati. L’ID funziona come <window> per gli altri comandi; con fzf puoi scegliere le finestre e raggrupparle:

Esempio
groupshelf list | fzf -m | cut -f1 | xargs groupshelf group

help

groupshelf help [<command>]

Mostra l’elenco dei comandi o l’uso di uno di essi: group, add, detach, ungroup o list.

Esempio
groupshelf help group

version

groupshelf version

Mostra la versione e la build del GroupShelf con cui è arrivato il comando. I due sono sempre la stessa build.

Codice di uscita

Gli script possono agire in base al codice di uscita. I messaggi vanno sullo standard error e iniziano tutti con groupshelf:.

0
Successo.
1
GroupShelf ha segnalato un errore: la richiesta va corretta, ad esempio un’app che non è aperta. Conta anche un gruppo formato senza alcune delle sue finestre.
2
Errore di utilizzo: la riga di comando stessa è sbagliata. Il comando indica cosa non va e ne mostra l’uso, senza contattare GroupShelf.
3
GroupShelf non è raggiungibile: la configurazione va corretta, ad esempio un’autorizzazione mancante.

Risoluzione dei problemi

Cosa significa ogni messaggio e cosa fare. Nomi e numeri al loro interno sono esempi: i tuoi riportano ciò che hai digitato.

Raggiungere GroupShelf · Codice di uscita 3

groupshelf: GroupShelf.app not found

Il comando non trova il GroupShelf con cui è arrivato: è una copia tenuta fuori dall’app e non è installato alcun GroupShelf. Installa GroupShelf, poi collega il comando come in “Installazione” invece di copiarlo.

groupshelf: GroupShelf could not be launched: <reason>

GroupShelf non era aperto e macOS non è riuscito ad aprirlo, per il motivo indicato. Apri GroupShelf tu stesso, poi esegui di nuovo il comando.

groupshelf: GroupShelf did not start within 15 seconds

GroupShelf è stato aperto in background, ma non era pronto in tempo. Esegui di nuovo il comando.

groupshelf: GroupShelf did not answer in time; if macOS asked whether your terminal app may control GroupShelf, answer that and try again

Il più delle volte macOS sta ancora aspettando la tua risposta alla richiesta di autorizzazione. Rispondi, poi esegui di nuovo il comando.

groupshelf: not allowed to control GroupShelf; allow your terminal app in System Settings › Privacy & Security › Automation

La tua app di terminale non può controllare GroupShelf. In Impostazioni di Sistema › Privacy e sicurezza › Automazione, attiva GroupShelf sotto la tua app di terminale.

groupshelf: if Visual Studio Code doesn't list GroupShelf there, install VS Code's Apple silicon or Intel build; its Universal build can't ask macOS for this permission

Nel terminale di VS Code, questa riga segue quella sopra. Vedi Visual Studio Code in “Autorizzazioni”.

groupshelf: this version of GroupShelf doesn't support groupshelf; update GroupShelf

Il GroupShelf raggiunto dal comando è precedente al comando stesso, ad esempio una vecchia copia altrove sul Mac. Aggiorna GroupShelf alla 1.3.0 o successiva e rimuovi le vecchie copie.

groupshelf: could not reach GroupShelf (error <number>)

macOS non è riuscito a consegnare la richiesta per un altro motivo; il numero è il suo codice di errore. Esci da GroupShelf, riaprilo e riprova. Se continua a succedere, contatta il supporto indicando il numero.

Impostazioni e stato di GroupShelf · Codice di uscita 1

groupshelf: control from the command line is off; turn on "Allow control from the command line and scripts" in GroupShelf Settings › Command Line

Attiva l’interruttore in Impostazioni › Riga di comando, come in “Attivazione”.

groupshelf: GroupShelf needs Accessibility access; allow it in System Settings › Privacy & Security › Accessibility

Senza di essa, GroupShelf non può spostare le finestre. Attiva GroupShelf in Impostazioni di Sistema › Privacy e sicurezza › Accessibilità.

groupshelf: GroupShelf is paused while Stage Manager is on

GroupShelf non può funzionare insieme a Stage Manager. Disattiva Stage Manager in Impostazioni di Sistema, poi riavvia GroupShelf.

groupshelf: GroupShelf hasn't finished starting; try again

Esegui di nuovo il comando tra un momento.

groupshelf: another group request is still running

GroupShelf gestisce una richiesta alla volta, e group e add possono attendere le finestre fino a 30 secondi. Esegui di nuovo il comando quando l’altra richiesta è finita.

groupshelf: "Slack" is excluded from grouping in GroupShelf settings

L’app è in “App escluse” in Impostazioni › Raggruppamento. Rimuovila da lì per raggrupparne le finestre.

Indicare le finestre · Codice di uscita 1

groupshelf: "Safari" isn't running; open it first — groupshelf only works with windows already open

Apri prima l’app. group e add attendono poi la sua finestra fino a 30 secondi.

groupshelf: no application named "Safary"

Controlla come è scritto. Un’app che non è aperta e non si trova in una cartella Applicazioni si può indicare solo con l’ID del bundle o il percorso.

groupshelf: "/Applications/Utilities" is not an application

Il percorso porta a qualcosa che non è un’app. Fallo puntare al .app stesso.

groupshelf: "Terminal:proj" fits 2 windows ("proj-a — zsh", "proj-b — zsh"); give more of the title, a window ID from groupshelf list, or --frontmost or --all

I titoli di più finestre contengono il testo. Restringi la scelta in uno dei modi indicati dal messaggio.

groupshelf: no window 4211 on this desktop; groupshelf list shows the windows there

La finestra è stata chiusa, oppure è su un’altra scrivania o a tutto schermo. Esegui groupshelf list per gli ID attuali.

groupshelf: no window for "Slack" on this desktop

detach, ungroup e un <member> considerano solo le finestre già presenti su questa scrivania, senza attendere. Controlla che la finestra sia aperta qui.

groupshelf: "4211" names a window another argument already names

Due argomenti indicano la stessa finestra. Rimuovine uno.

groupshelf: GroupShelf can't group its own windows

Togli GroupShelf dal comando.

Indicare i gruppi · Codice di uscita 1

groupshelf: no group named "Work"

Nessun gruppo ha quel nome. groupshelf list mostra il nome del gruppo di ogni finestra nel quinto campo.

groupshelf: --group "Work" fits 2 groups; name the group by one of its windows instead

Più gruppi hanno quel nome. Indica invece il gruppo con una delle sue finestre, come <member>.

groupshelf: the group of "Work" isn't on this desktop

add aggiunge solo a un gruppo su questa scrivania. Passa alla scrivania del gruppo ed esegui il comando lì.

groupshelf: "Safari" isn't in a group; groupshelf group makes one

La finestra indicata come <member> non è in alcun gruppo. Creane uno con group.

Risultati parziali · Codice di uscita 1

groupshelf: grouped 3 windows; no window for "Mail" on this desktop within 30 seconds
groupshelf: added 1 window; no window for "Mail" on this desktop within 30 seconds
groupshelf: nothing added; no window for "Mail" on this desktop within 30 seconds

Tutto ciò che precede il primo punto e virgola è stato fatto. Mancano le finestre elencate dopo: nessuna è comparsa su questa scrivania entro 30 secondi.

groupshelf: no group created: only 1 window to group; no window for "Mail" on this desktop within 30 seconds

Sono state trovate meno di due finestre, quindi non è stato cambiato nulla.

groupshelf: grouped 2 windows; "Mail" could not be added to the group

Il gruppo della finestra, o quello a cui si unirebbe, è bloccato. Fai clic con il tasto destro sulla barra dei pannelli del gruppo bloccato, scegli “Sblocca gruppo”, poi esegui di nuovo il comando.

Errori di utilizzo · Codice di uscita 2

groupshelf: unknown option '--names'
Usage: groupshelf group [--name <name>] [--all | --frontmost] <window> <window>...
Run 'groupshelf help group' for more.

La riga di comando stessa è sbagliata: la prima riga dice cosa non va, seguita dall’uso del comando. Non è stato inviato nulla a GroupShelf.

← Torna alla home