This might be a stupid question, but hear me out.
I regularly document steps to install various software for myself on my wiki
More recently, I managed to use different custom text in the source markdown to prepend # and $ automatically, so commands can be copied more easily while still clarifying if it should be run as a normal user or as root.

Run command as user

$ some cool command

Run command as root/superuser with sudo

# some dangerous command

I usually remove and sudo and use the # prefix. However, in some cases, the sudo actually does something different that needs to be highlighted. For example, I might use it to execute a command as the user www-data

sudo -u www-data cp /var/www/html/html1 /var/www/html/html2

I often use $ as a prefix, but # would also make sense.
How would you prefix that line?

  • canpolat@programming.dev
    link
    fedilink
    English
    arrow-up
    14
    arrow-down
    1
    ·
    edit-2
    1 year ago

    I don’t work much with Linux systems these days, but I would vote for $ sudo over #. Two reasons:

    1. It’s easy to overlook the prompt. That part is basically “some characters before the actual command”, so I don’t normally pay attention to it.
    2. # is also used for comments. I think it would be confusing to use the same character for two wildly different things.
    • exu@feditown.comOP
      link
      fedilink
      English
      arrow-up
      3
      ·
      1 year ago

      So $ sudo in general any time I need to run something as root?
      I’ll have to think about that some more. I think I rather dislike “forcing” sudo on all commands as root.

      • canpolat@programming.dev
        link
        fedilink
        English
        arrow-up
        3
        ·
        1 year ago

        Ok, maybe I misunderstood your question. I though you were proposing # instead of $ sudo and I meant to say that being explicit is better.

        • exu@feditown.comOP
          link
          fedilink
          English
          arrow-up
          1
          ·
          1 year ago

          I typed the post in a minute and published, so it definitely isn’t the most coherent or well thought out post.
          I’m currently using # for commands executed by the root user or sudo.
          Currently, I only use sudo if the command depends on one of its features. Like the example above where I execute a command as the www-data user.
          My dilemma was whether to use $ sudo or # sudo for those few cases. But based on yours and other comments, it might make sense to use $ sudo for commands executed as root as well.

  • smo@lemmy.sdf.org
    link
    fedilink
    English
    arrow-up
    7
    ·
    1 year ago

    I have a fairly opinionated stance on this. Except in your sudo example where you’re specifically using sudo for a reason, I document all commands as non-root, and do not instruct them to raise privs. Whether or not they have, want or need privs, and how they raise them, is their system not mine.

    It’s not exactly user friendly, but I don’t like to encourage people to blindly copy & paste commands that raise privs. That should be a conscious decision where they stop and ask themselves if & why it’s necessary.

  • ash@lemmy.fmhy.ml
    link
    fedilink
    English
    arrow-up
    6
    ·
    1 year ago

    I dislike when documentations add sudo because what if I am root already or what if sudo is not installed on my machine and I cannot just copy and paste the lines because I have to avoid pasting sudo.

    Also fyi ArchWiki also uses the # approach.

      • ash@lemmy.fmhy.ml
        link
        fedilink
        English
        arrow-up
        1
        ·
        1 year ago

        Sometimes the commands contain pipes or &&, which is a minor nitpick, but I still prefer # over sudo in documentation.

  • StudioLE@programming.dev
    link
    fedilink
    English
    arrow-up
    5
    ·
    1 year ago

    You should consider who your audience is, are they all CLI experts familiar with the difference in syntax? That seems unlikely.

    I’d always write documentation in a way that’s accessible to most users. The difference between $ and # syntax is highly esoteric.

    sudo on the other hand is familiar to almost everyone. It’s one of the first things mentioned in beginners guides.

    I wouldn’t even prefix your commands with $ as an experienced user is quite likely to include that when copying the command.

    A lot of people are citing the arch wiki as a standard that uses # but isn’t the entire meme around arch that its a notably complex system?

    • JeremyT@lemmy.teaisatfour.com
      link
      fedilink
      English
      arrow-up
      1
      ·
      1 year ago

      It’s ok if you prefix with $ and # IF it’s not selectable. It should only be a visual reference for those who know and only helps keep your documentation complete.

  • False@lemmy.world
    link
    fedilink
    English
    arrow-up
    7
    arrow-down
    2
    ·
    1 year ago

    Neither because it makes it hard to copy paste. If you have to pick one then $ because # is for comments in bash.

    • bjornsno@lemm.ee
      link
      fedilink
      English
      arrow-up
      6
      ·
      1 year ago

      You can just get around this by using some css tricks to display the dollar and pound signs.

    • exu@feditown.comOP
      link
      fedilink
      English
      arrow-up
      1
      ·
      1 year ago

      It’s not actually part of the command, just some css to add the prefix visually.

      • beeng@lemmy.fmhy.ml
        link
        fedilink
        English
        arrow-up
        1
        ·
        1 year ago

        That’s OK then. If you can double click the text field the the prefix is not highlighted, then I’m happy :)

  • bakavic@latte.isnot.coffee
    link
    fedilink
    English
    arrow-up
    5
    ·
    1 year ago

    I would use $ too for the example you’ve posted - it is just assuming a different user.

    As long as it is not root, I wouldn’t put it with #.

  • ProxyZeus@lemmy.world
    link
    fedilink
    English
    arrow-up
    5
    arrow-down
    1
    ·
    1 year ago

    Personally i prefer the $ sudo because honestly i don’t always notice the symbol at the beginning but sudo is really easy to keep track of whats root and what isn’t

  • james@lurk.fun
    link
    fedilink
    English
    arrow-up
    5
    arrow-down
    1
    ·
    edit-2
    1 year ago

    Edit: looks like this is wrong lol, that’s what I get for not verifying. So maybe $ does make more sense!

    Original message:

    I think I’d go with #.

    The non-root user probably doesn’t have permission to run the sudo command as www-data user, but root does.

    Unless you previously set permissions for the non-root user to sudo as www-data.

    • bizdelnick@lemmy.ml
      link
      fedilink
      English
      arrow-up
      2
      ·
      1 year ago

      The non-root user probably doesn’t have permission to run the sudo command as www-data user, but root does.

      You are wrong. E. g. in Debian (and Ubuntu) the default sudoers file contains

      %sudo   ALL=(ALL:ALL) ALL
      

      that means that any user in the sudo group is permitted to execute any command as any other user. The same for redhat/fedora, but the group name is wheel there.

  • bizdelnick@lemmy.ml
    link
    fedilink
    English
    arrow-up
    5
    arrow-down
    1
    ·
    1 year ago

    # is a standard shell prompt for root, and only for root. For commands executed by any other user, including sudo, use $.

    In general it is a bad practice to use sudo in documentation because in many distros it is not available by default. I would use su for your example. However system users have no passwords, so you need to become root first, and only after that change user to avoid prompting a password. So I would write

    # su -s /bin/bash www-data
    $ cp /var/www/html/html1 /var/www/html/html2
    

    or

    # su -s /bin/sh -c 'cp /var/www/html/html1 /var/www/html/html2' www-data
    

    But if you are sure that sudo is installed and configured on a user’s machine, you may write

    $ sudo -u www-data cp /var/www/html/html1 /var/www/html/html2
    
    • MimicJar@lemmy.world
      link
      fedilink
      English
      arrow-up
      2
      ·
      1 year ago

      I disagree completely.

      The bad practice is running commands directly as root. It’s fine if you prefer for your own environment but sudo is the best practice.

      Additionally, which distro doesn’t have sudo? I’m sure there are some but by far the majority of distos have and use sudo.

      • bizdelnick@lemmy.ml
        link
        fedilink
        English
        arrow-up
        1
        ·
        1 year ago

        Bad practice is not using sudo (I do use it), but assuming that everyone has sudo installed and configured the same way as you have.

        Additionally, which distro doesn’t have sudo? I’m sure there are some but by far the majority of distos have and use sudo.

        Almost all distros have sudo. But many of them don’t install it by default. Most popular distros except Ubuntu (I mean Debian, Fedora and RHEL clones) provide a choice to user at install time: set the root password or install sudo and enable it for the admin user. In OpenSUSE sudo is installed by default, however it is configured in slightly different way than usually. Etc., etc.

    • exu@feditown.comOP
      link
      fedilink
      English
      arrow-up
      1
      ·
      1 year ago

      Agreed that it’s bad practice to use sudo.
      Very good idea using su. I never thought of using it like that before.

  • 418teapot@lemmy.world
    link
    fedilink
    English
    arrow-up
    4
    ·
    1 year ago

    I seem to be in the minority here but I personally prefer using $ and # to denote root. I like this because not everyone uses sudo and might not even have it installed.

    That being said, if you already have other commands that are using sudo -u ... to run commands as a different user then it might be best to just be consistent and prefix everything with it, but if there is only a few of those maybe a # cp foo bar && chown www-data bar is an alternative.

    • exu@feditown.comOP
      link
      fedilink
      English
      arrow-up
      2
      ·
      1 year ago

      Yeah, being consistent is definitely important. I can avoid sudo in many cases, but there are other pages where half the commands need to be executed as some user.
      My Nextcloud page has that problem where php scripts need to be executed by the right user. But it also contains the installation instructions and there I can avoid using sudo. It’s like a 50/50 split between using # and sudo -u on that page :/